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 283 - reg 284 Usage: 285 286 Register base address of non-volatile counter and it is required 287 property. 288 289 Value type: <u32> 290 291 - oid 292 Usage: 293 294 This property provides the Object ID of non-volatile counter 295 provided in the certificate and it is required property. 296 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 325This binding document needs to be revisited to generalise some terminologies 326which are currently specific to X.509 certificates for e.g. Object IDs. 327 328*Copyright (c) 2020, Arm Limited. All rights reserved.* 329