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