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.* 288