doc: certificate format

Change-Id: I9d6427ed5e5fab159b5f96fab8b977b4371f26c3
Refs: #2861
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         |
++---------------------------------------------+-------------------+----------------+