docs/specs/certificate-format.rst

.. _NDN Certificate Format Version 2.0:

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 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 structure of the NDN certificates and is complementary to NDN packet
specification.

::

                              Overview of NDN certificate format
                                 +--------------------------+
                                 |           Name           |
                                 +--------------------------+
                                 |         MetaInfo         |
                                 |+------------------------+|
                                 || ContentType:  KEY(2)   ||
                                 |+------------------------+|
                                 |+------------------------+|
                                 || FreshnessPeriod: >~ 1h ||
                                 |+------------------------+|
                                 +--------------------------+
                                 |          Content         |
                                 |+------------------------+|
                                 ||       Public Key       ||
                                 |+------------------------+|
                                 +--------------------------+
                                 |       SignatureInfo      |
                                 |+------------------------+|
                                 || SignatureType:  ...    ||
                                 || KeyLocator:     ...    ||
                                 || ValidityPeriod: ...    ||
                                 || ...                    ||
                                 |+------------------------+|
                                 +--------------------------+
                                 |       SignatureValue     |
                                 +--------------------------+

.. code-block:: abnf

    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


Name
----

The name of a certificate consists of five parts as shown below::

    /<SubjectName>/KEY/[KeyId]/[IssuerId]/[Version]

A certificate name starts with the subject to which a public key is bound.  The following parts
include the keyword ``KEY`` component, KeyId, IssuerId, and version components.

``KeyId`` is an opaque name component to identify an instance of the public key for the
certificate namespace.  The value of `Key ID` is controlled by the namespace owner and can be
an 8-byte random number, SHA-256 digest of the public key, timestamp, or a simple numerical
identifier.

``Issuer Id`` is an opaque name component to identify issuer of the certificate.  The value is
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::

      /edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/%FD%d2...%8E
      \_________________/    \___________/ \___________/\___________/
     Certificate Namespace      Key Id       Issuer Id     Version
          (Identity)

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
-------------

The SignatureInfo block of a certificate is required to include the ``ValidityPeriod`` field.
``ValidityPeriod`` includes two sub TLV fields: ``NotBefore`` and ``NotAfter``, which carry 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 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
                       NotAfter

    NotBefore = NOT-BEFORE-TYPE TLV-LENGTH 8DIGIT "T" 6DIGIT

    NotAfter = NOT-AFTER-TYPE TLV-LENGTH 8DIGIT "T" 6DIGIT

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           |
+---------------------------------------------+-------------------+----------------+

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.  A
critical extension implies that if a validator cannot recognize or parse the
extension, the validator must reject the certificate.  A 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.

Extensions
----------

We list currently defined extensions:

+---------------------------------------------+-------------------+----------------+
| TLV-TYPE                                    | Assigned number   | Assigned number|
|                                             | (decimal)         | (hexadecimal)  |
+=============================================+===================+================+
| AdditionalDescription (non-critical)        | 258               | 0x0102         |
+---------------------------------------------+-------------------+----------------+

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.

.. 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

+---------------------------------------------+-------------------+----------------+
| TLV-TYPE                                    | Assigned number   | Assigned number|
|                                             | (decimal)         | (hexadecimal)  |
+=============================================+===================+================+
| DescriptionEntry                            | 512               | 0x0200         |
+---------------------------------------------+-------------------+----------------+
| DescriptionKey                              | 513               | 0x0201         |
+---------------------------------------------+-------------------+----------------+
| DescriptionValue                            | 514               | 0x0202         |
+---------------------------------------------+-------------------+----------------+