doc: certificate format
Change-Id: I9d6427ed5e5fab159b5f96fab8b977b4371f26c3
Refs: #2861
diff --git a/docs/index.rst b/docs/index.rst
index 5543840..eaa0cb7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -33,6 +33,7 @@
+ :doc:`tutorials/utils-ndn-regex`
+ :doc:`tutorials/security-validator-config`
+ :doc:`tutorials/signed-interest`
+ + :doc:`tutorials/certificate-format`
- :doc:`manpages`
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index 5a6f175..d4bc089 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -8,3 +8,4 @@
tutorials/utils-ndn-regex
tutorials/security-validator-config
tutorials/signed-interest
+ tutorials/certificate-format
diff --git a/docs/tutorials/certificate-format.rst b/docs/tutorials/certificate-format.rst
new file mode 100644
index 0000000..0bb059f
--- /dev/null
+++ b/docs/tutorials/certificate-format.rst
@@ -0,0 +1,221 @@
+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
+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 components of the NDN certificates and is complementary to NDN packet
+specification.
+
+::
+
+ Overview of NDN certificate format
+ +--------------------------+
+ | Name |
+ +--------------------------+
+ | MetaInfo |
+ |+------------------------+|
+ || ContentType: KEY(2) ||
+ |+------------------------+|
+ +--------------------------+
+ | Content |
+ |+------------------------+|
+ || Public Key ||
+ |+------------------------+|
+ +--------------------------+
+ | SignatureInfo |
+ |+------------------------+|
+ || SignatureType: ... ||
+ || KeyLocator: ... ||
+ || ValidityPeriod: ... ||
+ || ... ||
+ |+------------------------+|
+ +--------------------------+
+ | SignatureValue |
+ +--------------------------+
+
+
+Name
+----
+
+The name of a certificate consists of four parts as shown below:
+
+::
+
+ /<PrincipalName>/[KeyId]/KEY/[Version]
+
+A certificate name starts with the name to which a public key is bound. The
+second part is a single name component, called KeyId, which should uniquely
+identify the key under the principal namespace. The value of KeyId is up to
+the owner of the principal namespace (e.g., SHA-256 digest of the public key,
+timestamp, or numerical identifier). A special name component ``KEY`` is
+appended after KeyId, which indicates that the data is a certificate. The last
+component is version number. For example,
+
+::
+
+ /edu/ucla/cs/yingdi/%03%CD...%F1/KEY/%FD%d2...%8E
+ \_________________/\___________/ \___________/
+ Principal Name Key ID Version
+
+
+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
+-------------
+
+Besides, ``SignatureType`` and ``KeyLocator``, the ``SignatureInfo`` field of a
+certificate include more optional fields.
+
+::
+
+ SignatureInfo ::= SIGNATURE-INFO-TYPE TLV-LENGTH
+ SignatureType
+ KeyLocator
+ ValidityPeriod?
+ ... (SignatureInfo Extension TLVs)
+
+One optional field is ``ValidityPeriod``, which contains two sub TLV fields:
+``NotBefore`` and ``NotAfter``, which are 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 validity period of
+ certificate, which has been adopted by many certificate systems, such as
+ X.509, PGP, and DNSSEC.
+
+::
+
+ ValidityPeriod ::= VALIDITY-PERIOD-TYPE TLV-LENGTH
+ NotBefore
+ NotAfter
+
+ NotBefore ::= NOT-BEFORE-TYPE TLV-LENGTH
+ BYTE{15}
+
+ NotAfter ::= NOT-AFTER-TYPE TLV-LENGTH
+ BYTE{15}
+
+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 |
++---------------------------------------------+-------------------+----------------+
+
+.. note::
+ TLV-TYPE code that falls into [253, 65536) is encoded in
+ `3-byte <http://named-data.net/doc/ndn-tlv/tlv.html#variable-size-encoding-for-type-t-and-length-l>`__
+
+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. An
+critical extension implies that if a validator cannot recognize or cannot parse the
+extension, the validator must reject the certificate. An 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. For example, TLV-TYPE codes 256 and 257 are allocated to the
+``StatusChecking`` extension, 256 for critical StatusChecking while 257 for
+non-critical StatusChecking.
+
+
+Proposed Extensions
+-------------------
+
+We list the proposed extensions here:
+
++---------------------------------------------+-------------------+----------------+
+| TLV-TYPE | Assigned code | Assigned code |
+| | (decimal) | (hexadecimal) |
++=============================================+===================+================+
+| StatusChecking (Non-critical) | 256 | 0x0100 |
++---------------------------------------------+-------------------+----------------+
+| StatusChecking (Critical) | 257 | 0x0101 |
++---------------------------------------------+-------------------+----------------+
+| AdditionalDescription (Non-critical) | 258 | 0x0102 |
++---------------------------------------------+-------------------+----------------+
+| MultipleSignature (Critical) | 259 | 0x0103 |
++---------------------------------------------+-------------------+----------------+
+
+.. note::
+ TLV-TYPE code that falls into [253, 65536) is encoded in
+ `3-byte <http://named-data.net/doc/ndn-tlv/tlv.html#variable-size-encoding-for-type-t-and-length-l>`__
+
+Status Checking
+~~~~~~~~~~~~~~~
+
+TBD
+
+Multiple Signature
+~~~~~~~~~~~~~~~~~~
+
+TBD
+
+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.
+
+::
+
+ AdditionalDescription ::= ADDITIONAL-DESCRIPTION-TYPE TLV-LENGTH
+ DescriptionEntry+
+
+ DescriptionEntry ::= DESCRIPTION-ENTRY-TYPE TLV-LENGTH
+ DescriptionKey
+ DescriptionValue
+
+ DescriptionKey ::= DESCRIPTION-KEY-TYPE TLV-LENGTH
+ BYTE+
+
+ DescriptionValue ::= DESCRIPTION-VALUE-TYPE TLV-LENGTH
+ BYTE+
+
++---------------------------------------------+-------------------+----------------+
+| TLV-TYPE | Assigned code | Assigned code |
+| | (decimal) | (hexadecimal) |
++=============================================+===================+================+
+| DescriptionEntry | 512 | 0x0200 |
++---------------------------------------------+-------------------+----------------+
+| DescriptionKey | 513 | 0x0201 |
++---------------------------------------------+-------------------+----------------+
+| DescriptionValue | 514 | 0x0202 |
++---------------------------------------------+-------------------+----------------+