blob: f1ec424252b69f66ddc08475c0ed13acdc763057 [file] [log] [blame]
.. _NDN Certificate Format Version 2.0:
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 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 |
+--------------------------+
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.
::
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.
::
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 |
+---------------------------------------------+-------------------+----------------+