blob: 2808bc8082e2f5e7186e0458b37cdfc2e95af907 [file] [log] [blame]
Davide Pesaventocad94b02021-04-09 21:23:03 -04001NDN Certificate Format Version 2.0
2==================================
3
4Since signature verification is a common operation in NDN applications, it is
5important to define a common certificate format to standardize the public key
6authentication procedure. As every NDN data packet is signed, a data packet
7that carries a public key as content is conceptually a certificate. However,
8the specification of a data packet alone is not sufficient to serve as the
9specification of a common NDN certificate format, because additional provisions
10are required for the latter. For example, a certificate follows a specific
11naming scheme and may need to include validity period, revocation information,
12etc. This specification defines the naming and structure of NDN certificates
13and is complementary to the `NDN packet specification
14<https://named-data.net/doc/NDN-packet-spec/current/>`__.
15
16::
17
18 Structure of an NDN certificate
19 +--------------------------+
20 | Name |
21 +--------------------------+
22 | MetaInfo |
23 |+------------------------+|
24 || ContentType: KEY(2) ||
25 |+------------------------+|
26 |+------------------------+|
27 || FreshnessPeriod: ~1h ||
28 |+------------------------+|
29 +--------------------------+
30 | Content |
31 |+------------------------+|
32 || Public Key ||
33 |+------------------------+|
34 +--------------------------+
35 | SignatureInfo |
36 |+------------------------+|
37 || SignatureType: ... ||
38 || KeyLocator: ... ||
39 || ValidityPeriod: ... ||
40 || ... ||
41 |+------------------------+|
42 +--------------------------+
43 | SignatureValue |
44 +--------------------------+
45
46.. code-block:: abnf
47
Davide Pesavento93101df2021-06-15 18:33:09 -040048 Certificate = DATA-TYPE TLV-LENGTH
49 Name ; /<IdentityName>/KEY/<KeyId>/<IssuerId>/<Version>
50 MetaInfo ; ContentType == KEY, FreshnessPeriod required
51 CertificateContent
52 CertificateSignatureInfo
53 SignatureValue
Davide Pesaventocad94b02021-04-09 21:23:03 -040054
Davide Pesavento93101df2021-06-15 18:33:09 -040055 CertificateContent = CONTENT-TYPE TLV-LENGTH SubjectPublicKeyInfo
Davide Pesaventocad94b02021-04-09 21:23:03 -040056
Davide Pesavento93101df2021-06-15 18:33:09 -040057 CertificateSignatureInfo = SIGNATURE-INFO-TYPE TLV-LENGTH
Davide Pesaventocad94b02021-04-09 21:23:03 -040058 SignatureType
59 KeyLocator
60 ValidityPeriod
Davide Pesavento93101df2021-06-15 18:33:09 -040061 *CertificateExtension
Davide Pesaventocad94b02021-04-09 21:23:03 -040062
63
64Name
65----
66
67The name of a certificate consists of five parts as shown below::
68
69 /<IdentityName>/KEY/<KeyId>/<IssuerId>/<Version>
70
71A certificate name starts with the name of the identity to which the public key is
72bound. The identity is followed by a literal ``KEY`` GenericNameComponent and by
73the *KeyId*, *IssuerId*, and *Version* components.
74
75*KeyId* is an opaque name component that identifies an instance of the public key in
76the certificate namespace. The value of *KeyId* is controlled by the namespace owner
77and can be an 8-byte random number, the SHA-256 digest of the certificate's public
78key, a timestamp, or any other unique numerical identifier.
79
80*IssuerId* is an opaque name component that identifies the issuer of the certificate.
81The value is controlled by the certificate issuer and, similar to *KeyId*, can be an
828-byte random number, the SHA-256 digest of the issuer's public key, or any other
83free-form identifier.
84
85*Version* represents the version number of the certificate. This component is encoded
86as a VersionNameComponent, following either revision 1 (marker-based) or revision 2
87(type-based) of the `NDN naming conventions
88<https://named-data.net/publications/techreports/ndn-tr-22-2-ndn-memo-naming-conventions/>`__.
89
90For example::
91
92 /edu/ucla/cs/yingdi/KEY/%03%CD...%F1/%9F%D3...%B7/v=1617592200702
93 \_________________/ \___________/\___________/\______________/
94 Identity Name KeyId IssuerId Version
95
96MetaInfo
97--------
98
99The ``ContentType`` must be set to ``KEY`` (2).
100
101The ``FreshnessPeriod`` must be explicitly specified. The recommended value is 3,600,000 (1 hour).
102
103Content
104-------
105
Davide Pesavento93101df2021-06-15 18:33:09 -0400106The ``Content`` element of a certificate contains the actual bits of the public key, formatted as
107a DER-encoded `SubjectPublicKeyInfo <https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.7>`__
Davide Pesaventocad94b02021-04-09 21:23:03 -0400108structure.
109
110SignatureInfo
111-------------
112
113The ``SignatureInfo`` element of a certificate is required to include a ``ValidityPeriod``
114element.
115
116``ValidityPeriod`` contains two TLV sub-elements: ``NotBefore`` and ``NotAfter``, each
117carrying a UTC timestamp in *ISO 8601-1:2019* compact format without the final "Z" character
118("YYYYMMDDThhmmss", e.g., "20201231T235959"). ``NotBefore`` indicates when the certificate
119takes effect while ``NotAfter`` indicates when the certificate expires.
120
121.. code-block:: abnf
122
123 ValidityPeriod = VALIDITY-PERIOD-TYPE TLV-LENGTH
124 NotBefore
125 NotAfter
126
127 NotBefore = NOT-BEFORE-TYPE TLV-LENGTH IsoDate "T" IsoTime
128
129 NotAfter = NOT-AFTER-TYPE TLV-LENGTH IsoDate "T" IsoTime
130
131 IsoDate = 8DIGIT ; YYYYMMDD (UTC)
132
133 IsoTime = 6DIGIT ; hhmmss (UTC)
134
135+---------------------------------------------+------------------+-----------------+
136| Type | Assigned number | Assigned number |
137| | (decimal) | (hexadecimal) |
138+=============================================+==================+=================+
139| ValidityPeriod | 253 | 0xFD |
140+---------------------------------------------+------------------+-----------------+
141| NotBefore | 254 | 0xFE |
142+---------------------------------------------+------------------+-----------------+
143| NotAfter | 255 | 0xFF |
144+---------------------------------------------+------------------+-----------------+
145
146Extensions
147----------
148
149A certificate may carry zero or more extension fields in its ``SignatureInfo`` element.
150An extension can be either critical or non-critical depending on its TLV-TYPE number.
151A critical TLV-TYPE means that if a validator cannot recognize or parse the extension,
152the validator must reject the whole certificate. Conversely, an extension with a
153non-critical TLV-TYPE may be ignored by the validator if it is not recognized. Refer to
154the general `evolvability rules
155<https://named-data.net/doc/NDN-packet-spec/current/tlv.html#considerations-for-evolvability-of-tlv-based-encoding>`__
156of the NDN packet format to determine whether a TLV-TYPE is critical or not.
157
158The TLV-TYPE number range [256, 511] is reserved for extensions. The currently defined
159extensions are listed in the table below.
160
161+---------------------------------------------+------------------+-----------------+
162| Type | Assigned number | Assigned number |
163| | (decimal) | (hexadecimal) |
164+=============================================+==================+=================+
165| AdditionalDescription (non-critical) | 258 | 0x102 |
166+---------------------------------------------+------------------+-----------------+
167
168AdditionalDescription
169~~~~~~~~~~~~~~~~~~~~~
170
171``AdditionalDescription`` is a non-critical extension that provides additional
172information about the certificate. The information is expressed as a set of
173key-value pairs. Both key and value are UTF-8 strings, e.g.,
174``("Organization", "UCLA")``. The issuer of a certificate can specify arbitrary
175key-value pairs to provide further details about the certificate.
176
177.. code-block:: abnf
178
Davide Pesavento93101df2021-06-15 18:33:09 -0400179 CertificateExtension = AdditionalDescription
Davide Pesaventocad94b02021-04-09 21:23:03 -0400180
181 AdditionalDescription = ADDITIONAL-DESCRIPTION-TYPE TLV-LENGTH
182 1*DescriptionEntry
183
184 DescriptionEntry = DESCRIPTION-ENTRY-TYPE TLV-LENGTH
185 DescriptionKey
186 DescriptionValue
187
188 DescriptionKey = DESCRIPTION-KEY-TYPE TLV-LENGTH 1*OCTET
189
190 DescriptionValue = DESCRIPTION-VALUE-TYPE TLV-LENGTH 1*OCTET
191
192+---------------------------------------------+------------------+-----------------+
193| Type | Assigned number | Assigned number |
194| | (decimal) | (hexadecimal) |
195+=============================================+==================+=================+
196| DescriptionEntry | 512 | 0x200 |
197+---------------------------------------------+------------------+-----------------+
198| DescriptionKey | 513 | 0x201 |
199+---------------------------------------------+------------------+-----------------+
200| DescriptionValue | 514 | 0x202 |
201+---------------------------------------------+------------------+-----------------+