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                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.
78
79                Value type: <phandle>
80
81        - antirollback-counter
82                Usage:
83
84                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.
90
91                Value type: <phandle>
92
93
94        SUBNODES
95            - Description:
96
97              Hash and public key information present in the certificate
98              are shown by these nodes.
99
100            - public key node
101                  Description: Provide public key information in the certificate.
102
103                  PROPERTIES
104
105                  - oid
106                     Usage:
107
108                     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>
127
128Example:
129
130.. code:: c
131
132   cot {
133      manifests {
134         compatible = "arm, cert-descs”
135
136         trusted-key-cert: trusted-key-cert {
137            root-certificate;
138            image-id = <TRUSTED_KEY_CERT_ID>;
139            antirollback-counter = <&trusted_nv_counter>;
140
141            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         };
148
149         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>;
154
155            scp_fw_content_pk: scp_fw_content_pk {
156               oid = SCP_FW_CONTENT_CERT_PK_OID;
157            };
158         };
159         .
160         .
161         .
162
163         next-certificate {
164
165         };
166      };
167   };
168
169Images and Image node bindings definition
170-----------------------------------------
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
182                Definition: must be "arm, img-descs"
183
184- Image node
185        Description:
186
187        Describes image properties which will be used during
188        authentication process.
189
190        PROPERTIES
191
192        - image-id
193                Usage: Required for every image with unique id.
194
195                Value type: <u32>
196
197        - parent
198                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.
203
204                Value type: <phandle>
205
206        - hash
207                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.
212
213                Value type: <phandle>
214
215                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.
220
221Example:
222
223.. code:: c
224
225   cot {
226      images {
227         compatible = "arm, img-descs";
228
229         scp_bl2_image {
230            image-id = <SCP_BL2_IMAGE_ID>;
231            parent = <&scp_fw_content_cert>;
232            hash = <&scp_fw_hash>;
233         };
234
235         .
236         .
237         .
238
239         next-img {
240
241         };
242      };
243   };
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
265                Definition:
266
267                Must be set according to address size
268                of non-volatile counter register
269
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                - id
283                    Usage: Required for every nv-counter with unique id.
284
285                    Value type: <u32>
286
287                - reg
288                    Usage:
289
290                    Register base address of non-volatile counter and it is required
291                    property.
292
293                    Value type: <u32>
294
295                - oid
296                    Usage:
297
298                    This property provides the Object ID of non-volatile counter
299                    provided in the certificate and it is required property.
300
301                    Value type: <string>
302
303Example:
304Below is non-volatile counters example for ARM platform
305
306.. code:: c
307
308   non_volatile_counters: non_volatile_counters {
309        compatible = "arm, non-volatile-counter";
310        #address-cells = <1>;
311        #size-cells = <0>;
312
313        trusted-nv-counter: trusted_nv_counter {
314           id  = <TRUSTED_NV_CTR_ID>;
315           reg = <TFW_NVCTR_BASE>;
316           oid = TRUSTED_FW_NVCOUNTER_OID;
317        };
318
319        non_trusted_nv_counter: non_trusted_nv_counter {
320           id  = <NON_TRUSTED_NV_CTR_ID>;
321           reg = <NTFW_CTR_BASE>;
322           oid = NON_TRUSTED_FW_NVCOUNTER_OID;
323        };
324   };
325
326Future update to chain of trust binding
327---------------------------------------
328
329This binding document needs to be revisited to generalise some terminologies
330which are currently specific to X.509 certificates for e.g. Object IDs.
331
332*Copyright (c) 2020, Arm Limited. All rights reserved.*
333