blob: 46915db232cb1c85e7cd4e9340cf223e2b3af7f9 [file] [log] [blame]
Manish V Badarkhef3299202020-06-23 10:30:42 +01001Chain of trust bindings
2=======================
3
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +01004The device tree allows to describe the chain of trust with the help of
5'cot' node which contain 'manifests' and 'images' as sub-nodes.
6'manifests' and 'images' nodes contains number of sub-nodes (i.e. 'certificate'
7and 'image' nodes) mentioning properties of the certificate and image respectively.
Manish V Badarkhef3299202020-06-23 10:30:42 +01008
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +01009Also, device tree describes 'non-volatile-counters' node which contains number of
10sub-nodes mentioning properties of all non-volatile-counters used in the chain of trust.
Manish V Badarkhef3299202020-06-23 10:30:42 +010011
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010012cot
13------------------------------------------------------------------
14This is root node which contains 'manifests' and 'images' as sub-nodes
Manish V Badarkhef3299202020-06-23 10:30:42 +010015
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010016
17Manifests and Certificate node bindings definition
Manish V Badarkhef3299202020-06-23 10:30:42 +010018----------------------------------------------------------------
19
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010020- Manifests node
Manish V Badarkhef3299202020-06-23 10:30:42 +010021 Description: Container of certificate nodes.
22
23 PROPERTIES
24
25 - compatible:
26 Usage: required
27
28 Value type: <string>
29
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010030 Definition: must be "arm, cert-descs"
Manish V Badarkhef3299202020-06-23 10:30:42 +010031
32- Certificate node
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010033 Description:
34
35 Describes certificate properties which are used
36 during the authentication process.
Manish V Badarkhef3299202020-06-23 10:30:42 +010037
38 PROPERTIES
39
40 - root-certificate
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010041 Usage:
Manish V Badarkhef3299202020-06-23 10:30:42 +010042
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010043 Required for the certificate with no parent.
44 In other words, certificates which are validated
45 using root of trust public key.
46
47 Value type: <boolean>
Manish V Badarkhef3299202020-06-23 10:30:42 +010048
49 - image-id
50 Usage: Required for every certificate with unique id.
51
52 Value type: <u32>
53
54 - parent
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010055 Usage:
Manish V Badarkhef3299202020-06-23 10:30:42 +010056
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010057 It refers to their parent image, which typically contains
58 information to authenticate the certificate.
59 This property is required for all non-root certificates.
60
61 This property is not required for root-certificates
62 as root-certificates are validated using root of trust
63 public key provided by platform.
Manish V Badarkhef3299202020-06-23 10:30:42 +010064
65 Value type: <phandle>
66
67 - signing-key
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010068 Usage:
Manish V Badarkhef3299202020-06-23 10:30:42 +010069
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010070 This property is used to refer public key node present in
71 parent certificate node and it is required property for all
72 non-root certificates which are authenticated using public-key
73 present in parent certificate.
74
75 This property is not required for root-certificates
76 as root-certificates are validated using root of trust
77 public key provided by platform.
Manish V Badarkhef3299202020-06-23 10:30:42 +010078
79 Value type: <phandle>
80
81 - antirollback-counter
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010082 Usage:
Manish V Badarkhef3299202020-06-23 10:30:42 +010083
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010084 This property is used by all certificates which are
85 protected against rollback attacks using a non-volatile
86 counter and it is an optional property.
87
88 This property is used to refer one of the non-volatile
89 counter sub-node present in 'non-volatile counters' node.
Manish V Badarkhef3299202020-06-23 10:30:42 +010090
91 Value type: <phandle>
92
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010093
Manish V Badarkhef3299202020-06-23 10:30:42 +010094 SUBNODES
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010095 - Description:
Manish V Badarkhef3299202020-06-23 10:30:42 +010096
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +010097 Hash and public key information present in the certificate
98 are shown by these nodes.
Manish V Badarkhef3299202020-06-23 10:30:42 +010099
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100100 - public key node
101 Description: Provide public key information in the certificate.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100102
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100103 PROPERTIES
104
105 - oid
106 Usage:
Manish V Badarkhef3299202020-06-23 10:30:42 +0100107
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100108 This property provides the Object ID of public key
109 provided in the certificate which the help of which
110 public key information can be extracted.
111
112 Value type: <string>
113
114 - hash node
115 Description: Provide the hash information in the certificate.
116
117 PROPERTIES
118
119 - oid
120 Usage:
121
122 This property provides the Object ID of hash provided in
123 the certificate which the help of which hash information
124 can be extracted.
125
126 Value type: <string>
Manish V Badarkhef3299202020-06-23 10:30:42 +0100127
128Example:
129
130.. code:: c
131
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100132 cot {
133 manifests {
134 compatible = "arm, cert-descs”
Manish V Badarkhef3299202020-06-23 10:30:42 +0100135
136 trusted-key-cert: trusted-key-cert {
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100137 root-certificate;
138 image-id = <TRUSTED_KEY_CERT_ID>;
139 antirollback-counter = <&trusted_nv_counter>;
Manish V Badarkhef3299202020-06-23 10:30:42 +0100140
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100141 trusted-world-pk: trusted-world-pk {
142 oid = TRUSTED_WORLD_PK_OID;
143 };
144 non-trusted-world-pk: non-trusted-world-pk {
145 oid = NON_TRUSTED_WORLD_PK_OID;
146 };
147 };
Manish V Badarkhef3299202020-06-23 10:30:42 +0100148
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100149 scp_fw_key_cert: scp_fw_key_cert {
150 image-id = <SCP_FW_KEY_CERT_ID>;
151 parent = <&trusted-key-cert>;
152 signing-key = <&trusted_world_pk>;
153 antirollback-counter = <&trusted_nv_counter>;
Manish V Badarkhef3299202020-06-23 10:30:42 +0100154
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100155 scp_fw_content_pk: scp_fw_content_pk {
156 oid = SCP_FW_CONTENT_CERT_PK_OID;
157 };
158 };
159 .
160 .
161 .
Manish V Badarkhef3299202020-06-23 10:30:42 +0100162
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100163 next-certificate {
164
165 };
166 };
Manish V Badarkhef3299202020-06-23 10:30:42 +0100167 };
168
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100169Images and Image node bindings definition
Manish V Badarkhef3299202020-06-23 10:30:42 +0100170-----------------------------------------
171
172- Images node
173 Description: Container of image nodes
174
175 PROPERTIES
176
177 - compatible:
178 Usage: required
179
180 Value type: <string>
181
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100182 Definition: must be "arm, img-descs"
Manish V Badarkhef3299202020-06-23 10:30:42 +0100183
184- Image node
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100185 Description:
186
187 Describes image properties which will be used during
188 authentication process.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100189
190 PROPERTIES
191
192 - image-id
193 Usage: Required for every image with unique id.
194
195 Value type: <u32>
196
197 - parent
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100198 Usage:
199
200 Required for every image to provide a reference to
201 its parent image, which contains the necessary information
202 to authenticate it.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100203
204 Value type: <phandle>
205
206 - hash
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100207 Usage:
208
209 Required for all images which are validated using
210 hash method. This property is used to refer hash
211 node present in parent certificate node.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100212
213 Value type: <phandle>
214
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100215 Note:
216
217 Currently, all images are validated using 'hash'
218 method. In future, there may be multiple methods can
219 be used to validate the image.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100220
221Example:
222
223.. code:: c
224
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100225 cot {
226 images {
227 compatible = "arm, img-descs";
Manish V Badarkhef3299202020-06-23 10:30:42 +0100228
229 scp_bl2_image {
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100230 image-id = <SCP_BL2_IMAGE_ID>;
231 parent = <&scp_fw_content_cert>;
232 hash = <&scp_fw_hash>;
Manish V Badarkhef3299202020-06-23 10:30:42 +0100233 };
234
235 .
236 .
237 .
238
239 next-img {
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100240
Manish V Badarkhef3299202020-06-23 10:30:42 +0100241 };
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100242 };
Manish V Badarkhef3299202020-06-23 10:30:42 +0100243 };
244
245non-volatile counter node binding definition
246--------------------------------------------
247
248- non-volatile counters node
249 Description: Contains properties for non-volatile counters.
250
251 PROPERTIES
252
253 - compatible:
254 Usage: required
255
256 Value type: <string>
257
258 Definition: must be "arm, non-volatile-counter"
259
260 - #address-cells
261 Usage: required
262
263 Value type: <u32>
264
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100265 Definition:
266
267 Must be set according to address size
268 of non-volatile counter register
Manish V Badarkhef3299202020-06-23 10:30:42 +0100269
270 - #size-cells
271 Usage: required
272
273 Value type: <u32>
274
275 Definition: must be set to 0
276
277 SUBNODE
278 - counters node
279 Description: Contains various non-volatile counters present in the platform.
280
281 PROPERTIES
282
283 - reg
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100284 Usage:
285
286 Register base address of non-volatile counter and it is required
287 property.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100288
289 Value type: <u32>
290
291 - oid
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100292 Usage:
293
294 This property provides the Object ID of non-volatile counter
295 provided in the certificate and it is required property.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100296
297 Value type: <string>
298
299Example:
300Below is non-volatile counters example for ARM platform
301
302.. code:: c
303
304 non-volatile-counters {
305 compatible = "arm, non-volatile-counter";
306 #address-cells = <1>;
307 #size-cells = <0>;
308
309 counters {
310 trusted-nv-counter: trusted_nv_counter {
311 reg = <TFW_NVCTR_BASE>;
312 oid = TRUSTED_FW_NVCOUNTER_OID;
313 };
314 non_trusted_nv_counter: non_trusted_nv_counter {
315 reg = <NTFW_CTR_BASE>;
316 oid = NON_TRUSTED_FW_NVCOUNTER_OID;
317
318 };
319 };
320 };
321
322Future update to chain of trust binding
323---------------------------------------
324
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100325This binding document needs to be revisited to generalise some terminologies
326which are currently specific to X.509 certificates for e.g. Object IDs.
Manish V Badarkhef3299202020-06-23 10:30:42 +0100327
Manish V Badarkhe41dd13a2020-06-30 04:04:05 +0100328*Copyright (c) 2020, Arm Limited. All rights reserved.*