1Chain of trust bindings
2=======================
3
4The 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.
8
9Also, 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.
11
12cot
13------------------------------------------------------------------
14This is root node which contains 'manifests' and 'images' as sub-nodes
15
16
17Manifests and Certificate node bindings definition
18----------------------------------------------------------------
19
20- Manifests node
21        Description: Container of certificate nodes.
22
23        PROPERTIES
24
25        - compatible:
26                Usage: required
27
28                Value type: <string>
29
30                Definition: must be "arm, cert-descs"
31
32- Certificate node
33        Description:
34
35        Describes certificate properties which are used
36        during the authentication process.
37
38        PROPERTIES
39
40        - root-certificate
41               Usage:
42
43               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>
48
49        - image-id
50                Usage: Required for every certificate with unique id.
51
52                Value type: <u32>
53
54        - parent
55                Usage:
56
57                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.
64
65                Value type: <phandle>
66
67        - signing-key
68                Usage:
69
70                For non-root certificates, this property is used to refer
71                public key node present in parent certificate node and it is
72                required property for all non-root certificates which are
73                authenticated using public-key present in parent certificate.
74
75                This property is not required for all root-certificates. If
76                omitted, the root certificate will be validated using the
77                default platform ROTPK. If instead the root certificate needs
78                validating using a different ROTPK, the signing-key property
79                should provide a reference to the ROTPK node to use.
80
81                Value type: <phandle>
82
83        - antirollback-counter
84                Usage:
85
86                This property is used by all certificates which are
87                protected against rollback attacks using a non-volatile
88                counter and it is an optional property.
89
90                This property is used to refer one of the non-volatile
91                counter sub-node present in 'non-volatile counters' node.
92
93                Value type: <phandle>
94
95
96        SUBNODES
97            - Description:
98
99              Hash and public key information present in the certificate
100              are shown by these nodes.
101
102            - public key node
103                  Description: Provide public key information in the certificate.
104
105                  PROPERTIES
106
107                  - oid
108                     Usage:
109
110                     This property provides the Object ID of public key
111                     provided in the certificate which the help of which
112                     public key information can be extracted.
113
114                     Value type: <string>
115
116            - hash node
117                 Description: Provide the hash information in the certificate.
118
119                 PROPERTIES
120
121                 - oid
122                     Usage:
123
124                     This property provides the Object ID of hash provided in
125                     the certificate which the help of which hash information
126                     can be extracted.
127
128                     Value type: <string>
129
130Example:
131
132.. code:: c
133
134   cot {
135      manifests {
136         compatible = "arm, cert-descs”
137
138         trusted-key-cert: trusted-key-cert {
139            root-certificate;
140            image-id = <TRUSTED_KEY_CERT_ID>;
141            antirollback-counter = <&trusted_nv_counter>;
142
143            trusted-world-pk: trusted-world-pk {
144               oid = TRUSTED_WORLD_PK_OID;
145            };
146            non-trusted-world-pk: non-trusted-world-pk {
147               oid = NON_TRUSTED_WORLD_PK_OID;
148            };
149         };
150
151         scp_fw_key_cert: scp_fw_key_cert {
152            image-id = <SCP_FW_KEY_CERT_ID>;
153            parent = <&trusted-key-cert>;
154            signing-key = <&trusted_world_pk>;
155            antirollback-counter = <&trusted_nv_counter>;
156
157            scp_fw_content_pk: scp_fw_content_pk {
158               oid = SCP_FW_CONTENT_CERT_PK_OID;
159            };
160         };
161         .
162         .
163         .
164
165         next-certificate {
166
167         };
168      };
169   };
170
171Images and Image node bindings definition
172-----------------------------------------
173
174- Images node
175        Description: Container of image nodes
176
177        PROPERTIES
178
179        - compatible:
180                Usage: required
181
182                Value type: <string>
183
184                Definition: must be "arm, img-descs"
185
186- Image node
187        Description:
188
189        Describes image properties which will be used during
190        authentication process.
191
192        PROPERTIES
193
194        - image-id
195                Usage: Required for every image with unique id.
196
197                Value type: <u32>
198
199        - parent
200                Usage:
201
202                Required for every image to provide a reference to
203                its parent image, which contains the necessary information
204                to authenticate it.
205
206                Value type: <phandle>
207
208        - hash
209                Usage:
210
211                Required for all images which are validated using
212                hash method. This property is used to refer hash
213                node present in parent certificate node.
214
215                Value type: <phandle>
216
217                Note:
218
219                Currently, all images are validated using 'hash'
220                method. In future, there may be multiple methods can
221                be used to validate the image.
222
223Example:
224
225.. code:: c
226
227   cot {
228      images {
229         compatible = "arm, img-descs";
230
231         scp_bl2_image {
232            image-id = <SCP_BL2_IMAGE_ID>;
233            parent = <&scp_fw_content_cert>;
234            hash = <&scp_fw_hash>;
235         };
236
237         .
238         .
239         .
240
241         next-img {
242
243         };
244      };
245   };
246
247non-volatile counter node binding definition
248--------------------------------------------
249
250- non-volatile counters node
251        Description: Contains properties for non-volatile counters.
252
253        PROPERTIES
254
255        - compatible:
256                Usage: required
257
258                Value type: <string>
259
260                Definition: must be "arm, non-volatile-counter"
261
262        - #address-cells
263                Usage: required
264
265                Value type: <u32>
266
267                Definition:
268
269                Must be set according to address size
270                of non-volatile counter register
271
272        - #size-cells
273                Usage: required
274
275                Value type: <u32>
276
277                Definition: must be set to 0
278
279        SUBNODE
280            - counters node
281                    Description: Contains various non-volatile counters present in the platform.
282
283            PROPERTIES
284                - id
285                    Usage: Required for every nv-counter with unique id.
286
287                    Value type: <u32>
288
289                - reg
290                    Usage:
291
292                    Register base address of non-volatile counter and it is required
293                    property.
294
295                    Value type: <u32>
296
297                - oid
298                    Usage:
299
300                    This property provides the Object ID of non-volatile counter
301                    provided in the certificate and it is required property.
302
303                    Value type: <string>
304
305Example:
306Below is non-volatile counters example for ARM platform
307
308.. code:: c
309
310   non_volatile_counters: non_volatile_counters {
311        compatible = "arm, non-volatile-counter";
312        #address-cells = <1>;
313        #size-cells = <0>;
314
315        trusted-nv-counter: trusted_nv_counter {
316           id  = <TRUSTED_NV_CTR_ID>;
317           reg = <TFW_NVCTR_BASE>;
318           oid = TRUSTED_FW_NVCOUNTER_OID;
319        };
320
321        non_trusted_nv_counter: non_trusted_nv_counter {
322           id  = <NON_TRUSTED_NV_CTR_ID>;
323           reg = <NTFW_CTR_BASE>;
324           oid = NON_TRUSTED_FW_NVCOUNTER_OID;
325        };
326   };
327
328rot_keys node binding definition
329---------------------------------
330
331- rot_keys node
332        Description: Contains root-of-trust keys for the root certificates.
333
334        SUBNODES
335            - Description:
336
337              Root of trust key information present in the root certificates
338              are shown by these nodes.
339
340            - rot key node
341                  Description: Provide ROT key information in the certificate.
342
343                  PROPERTIES
344
345                  - oid
346                     Usage:
347
348                     This property provides the Object ID of ROT key provided
349                     in the certificate.
350
351                     Value type: <string>
352
353Example:
354Below is rot_keys example for CCA platform
355
356.. code:: c
357
358   rot_keys {
359        swd_rot_pk: swd_rot_pk {
360           oid = SWD_ROT_PK_OID;
361        };
362
363        prot_pk: prot_pk {
364           oid = PROT_PK_OID;
365        };
366   };
367
368Future update to chain of trust binding
369---------------------------------------
370
371This binding document needs to be revisited to generalise some terminologies
372which are currently specific to X.509 certificates for e.g. Object IDs.
373
374*Copyright (c) 2020-2024, Arm Limited. All rights reserved.*
375