Gitiles
Code Review Sign In
git01.mediatek.com / filogic / atf / 0cfbff9eba151e9d7bfc9a90fa2fed2d88a4b9b8 / . / docs / components / cot-binding.rst
blob: cc69d79b4a96b449bd5b29da0d37a7a3df074903 [file] [log] [blame]
Manish V Badarkhef3299202020-06-23 10:30:42 +0100[diff] [blame]1Chain of trust bindings
2=======================
3
4The device tree allows to describes the chain of trust with the help of
5certificates and images nodes, which in turn contains number of sub-nodes
6(i.e. certificate and image) mentioning properties for every certificate
7and image respectively.
8Also, this binding allows to describe OID of non-volatile counters, memory
9mapped address and size of non-volatile counter register.
10
11Convention used in this document
12--------------------------------
13
14This document follows the conventions described in the Device-tree
15Specification
16
17certificates, certificate and extension node bindings definition
18----------------------------------------------------------------
19
20- Certificates 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, certificate-descriptors"
31
32- Certificate node
33 Description: Describes certificate properties which are used
34 during the authentication process.
35
36 PROPERTIES
37
38 - root-certificate
39 Usage: Required for the certificate with no parent.
40 In other words, Certificates which are validated
41 using root of trust public key.
42
43 Value type: <boolean>
44
45 - image-id
46 Usage: Required for every certificate with unique id.
47
48 Value type: <u32>
49
50 - parent
51 Usage: It refers to their parent image, which typically contains
52 information to authenticate the certificate.
53 This property is required for all non-root certificates.
54
55 This property is not required for root-certificates
56 as it is validated using root of trust public key
57 provided by platform.
58
59 Value type: <phandle>
60
61 - signing-key
62 Usage: This property is used to refer extension node present in
63 parent certificate and it is required property for all non-
64 root certificates which are authenticated using public-key
65 present in parent certificate.
66
67 This property is not required for root-certificates
68 as root-certificates are validated using root of trust
69 public key provided by platform.
70
71 Value type: <phandle>
72
73 - antirollback-counter
74 Usage: This property is used by all certificates which are protected
75 against rollback attacks using a non-volatile counter and it
76 is optional property.
77
78 This property is used to refer trusted or non-trusted
79 non-volatile counter node.
80
81 Value type: <phandle>
82
83 SUBNODES
84
85 - extensions node
86 Description: This is sub-node of certificate node.
87 Describes OIDs present in the certificate which will
88 be used during authentication process to extract
89 hash/public key information from this certificate.
90 OIDs in extension node are represented using number of
91 sub-nodes which contains 'oid' as property
92
93 PROPERTIES
94
95 - oid
96 Usage: This property provides the Object ID of an extension
97 provided in the certificate.
98
99 Value type: <string>
100
101Example:
102
103.. code:: c
104
105 certificates {
106 compatible = "arm, certificate-descriptors”
107
108 trusted-key-cert: trusted-key-cert {
109 root-certificate;
110 image-id = <TRUSTED_KEY_CERT_ID>;
111 antirollback-counter = <&trusted_nv_counter>;
112 extensions {
113 trusted-world-pk: trusted-world-pk {
114 oid = TRUSTED_WORLD_PK_OID;
115 };
116 non-trusted-world-pk: non-trusted-world-pk {
117 oid = NON_TRUSTED_WORLD_PK_OID;
118 };
119 };
120 };
121
122 scp_fw_key_cert: scp_fw_key_cert {
123 image-id = <SCP_FW_KEY_CERT_ID>;
124 parent = <&trusted-key-cert>;
125 signing-key = <&trusted_world_pk>;
126 antirollback-counter = <&trusted_nv_counter>;
127 extensions {
128 scp_fw_content_pk: scp_fw_content_pk {
129 oid = SCP_FW_CONTENT_CERT_PK_OID;
130 };
131 };
132 };
133
134 .
135 .
136 .
137
138 next-cert {
139
140 };
141 };
142
143Images and image node bindings definition
144-----------------------------------------
145
146- Images node
147 Description: Container of image nodes
148
149 PROPERTIES
150
151 - compatible:
152 Usage: required
153
154 Value type: <string>
155
156 Definition: must be "arm, image-descriptors"
157
158- Image node
159 Description: Describes image properties which will be used during
160 authentication process.
161
162 PROPERTIES
163
164 - image-id
165 Usage: Required for every image with unique id.
166
167 Value type: <u32>
168
169 - parent
170 Usage: Required for every image to provide a reference to
171 it's parent image, which contains the necessary information
172 to authenticate it.
173
174 Value type: <phandle>
175
176 - hash
177 Usage: Required for all images which are validated using
178 hash method. This property is used to refer extension
179 node present in parent certificate and it is required
180 property for all images.
181
182 Value type: <phandle>
183
184 Note: Currently, all images are validated using "hash"
185 method. In future, there may be multiple methods can
186 be used to validate the image.
187
188Example:
189
190.. code:: c
191
192 images {
193 compatible = "arm, imgage-descriptors";
194
195 scp_bl2_image {
196 image-id = <SCP_BL2_IMAGE_ID>;
197 parent = <&scp_fw_content_cert>;
198 hash = <&scp_fw_hash>;
199 };
200
201 .
202 .
203 .
204
205 next-img {
206 };
207 };
208
209non-volatile counter node binding definition
210--------------------------------------------
211
212- non-volatile counters node
213 Description: Contains properties for non-volatile counters.
214
215 PROPERTIES
216
217 - compatible:
218 Usage: required
219
220 Value type: <string>
221
222 Definition: must be "arm, non-volatile-counter"
223
224 - #address-cells
225 Usage: required
226
227 Value type: <u32>
228
229 Definition: Must be set according to address size
230 of non-volatile counter register
231
232 - #size-cells
233 Usage: required
234
235 Value type: <u32>
236
237 Definition: must be set to 0
238
239 SUBNODE
240 - counters node
241 Description: Contains various non-volatile counters present in the platform.
242
243 PROPERTIES
244
245 - reg
246 Usage: Register base address of non-volatile counter and it is required
247 property.
248
249 Value type: <u32>
250
251 - oid
252 Usage: This property provides the Object ID of non-volatile counter
253 provided in the certificate and it is required property.
254
255 Value type: <string>
256
257Example:
258Below is non-volatile counters example for ARM platform
259
260.. code:: c
261
262 non-volatile-counters {
263 compatible = "arm, non-volatile-counter";
264 #address-cells = <1>;
265 #size-cells = <0>;
266
267 counters {
268 trusted-nv-counter: trusted_nv_counter {
269 reg = <TFW_NVCTR_BASE>;
270 oid = TRUSTED_FW_NVCOUNTER_OID;
271 };
272 non_trusted_nv_counter: non_trusted_nv_counter {
273 reg = <NTFW_CTR_BASE>;
274 oid = NON_TRUSTED_FW_NVCOUNTER_OID;
275
276 };
277 };
278 };
279
280Future update to chain of trust binding
281---------------------------------------
282
283This binding document need to be revisited to generalise some terminologies
284like Object IDs, extensions etc which are currently specific to X.509
285certificates.
286
287*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.*