diff options
Diffstat (limited to 'docs/components/cot-binding.rst')
| -rw-r--r-- | docs/components/cot-binding.rst | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst new file mode 100644 index 0000000..4f8c8b7 --- /dev/null +++ b/docs/components/cot-binding.rst @@ -0,0 +1,332 @@ +Chain of trust bindings +======================= + +The device tree allows to describe the chain of trust with the help of +'cot' node which contain 'manifests' and 'images' as sub-nodes. +'manifests' and 'images' nodes contains number of sub-nodes (i.e. 'certificate' +and 'image' nodes) mentioning properties of the certificate and image respectively. + +Also, device tree describes 'non-volatile-counters' node which contains number of +sub-nodes mentioning properties of all non-volatile-counters used in the chain of trust. + +cot +------------------------------------------------------------------ +This is root node which contains 'manifests' and 'images' as sub-nodes + + +Manifests and Certificate node bindings definition +---------------------------------------------------------------- + +- Manifests node + Description: Container of certificate nodes. + + PROPERTIES + + - compatible: + Usage: required + + Value type: <string> + + Definition: must be "arm, cert-descs" + +- Certificate node + Description: + + Describes certificate properties which are used + during the authentication process. + + PROPERTIES + + - root-certificate + Usage: + + Required for the certificate with no parent. + In other words, certificates which are validated + using root of trust public key. + + Value type: <boolean> + + - image-id + Usage: Required for every certificate with unique id. + + Value type: <u32> + + - parent + Usage: + + It refers to their parent image, which typically contains + information to authenticate the certificate. + This property is required for all non-root certificates. + + This property is not required for root-certificates + as root-certificates are validated using root of trust + public key provided by platform. + + Value type: <phandle> + + - signing-key + Usage: + + This property is used to refer public key node present in + parent certificate node and it is required property for all + non-root certificates which are authenticated using public-key + present in parent certificate. + + This property is not required for root-certificates + as root-certificates are validated using root of trust + public key provided by platform. + + Value type: <phandle> + + - antirollback-counter + Usage: + + This property is used by all certificates which are + protected against rollback attacks using a non-volatile + counter and it is an optional property. + + This property is used to refer one of the non-volatile + counter sub-node present in 'non-volatile counters' node. + + Value type: <phandle> + + + SUBNODES + - Description: + + Hash and public key information present in the certificate + are shown by these nodes. + + - public key node + Description: Provide public key information in the certificate. + + PROPERTIES + + - oid + Usage: + + This property provides the Object ID of public key + provided in the certificate which the help of which + public key information can be extracted. + + Value type: <string> + + - hash node + Description: Provide the hash information in the certificate. + + PROPERTIES + + - oid + Usage: + + This property provides the Object ID of hash provided in + the certificate which the help of which hash information + can be extracted. + + Value type: <string> + +Example: + +.. code:: c + + cot { + manifests { + compatible = "arm, cert-descs” + + trusted-key-cert: trusted-key-cert { + root-certificate; + image-id = <TRUSTED_KEY_CERT_ID>; + antirollback-counter = <&trusted_nv_counter>; + + trusted-world-pk: trusted-world-pk { + oid = TRUSTED_WORLD_PK_OID; + }; + non-trusted-world-pk: non-trusted-world-pk { + oid = NON_TRUSTED_WORLD_PK_OID; + }; + }; + + scp_fw_key_cert: scp_fw_key_cert { + image-id = <SCP_FW_KEY_CERT_ID>; + parent = <&trusted-key-cert>; + signing-key = <&trusted_world_pk>; + antirollback-counter = <&trusted_nv_counter>; + + scp_fw_content_pk: scp_fw_content_pk { + oid = SCP_FW_CONTENT_CERT_PK_OID; + }; + }; + . + . + . + + next-certificate { + + }; + }; + }; + +Images and Image node bindings definition +----------------------------------------- + +- Images node + Description: Container of image nodes + + PROPERTIES + + - compatible: + Usage: required + + Value type: <string> + + Definition: must be "arm, img-descs" + +- Image node + Description: + + Describes image properties which will be used during + authentication process. + + PROPERTIES + + - image-id + Usage: Required for every image with unique id. + + Value type: <u32> + + - parent + Usage: + + Required for every image to provide a reference to + its parent image, which contains the necessary information + to authenticate it. + + Value type: <phandle> + + - hash + Usage: + + Required for all images which are validated using + hash method. This property is used to refer hash + node present in parent certificate node. + + Value type: <phandle> + + Note: + + Currently, all images are validated using 'hash' + method. In future, there may be multiple methods can + be used to validate the image. + +Example: + +.. code:: c + + cot { + images { + compatible = "arm, img-descs"; + + scp_bl2_image { + image-id = <SCP_BL2_IMAGE_ID>; + parent = <&scp_fw_content_cert>; + hash = <&scp_fw_hash>; + }; + + . + . + . + + next-img { + + }; + }; + }; + +non-volatile counter node binding definition +-------------------------------------------- + +- non-volatile counters node + Description: Contains properties for non-volatile counters. + + PROPERTIES + + - compatible: + Usage: required + + Value type: <string> + + Definition: must be "arm, non-volatile-counter" + + - #address-cells + Usage: required + + Value type: <u32> + + Definition: + + Must be set according to address size + of non-volatile counter register + + - #size-cells + Usage: required + + Value type: <u32> + + Definition: must be set to 0 + + SUBNODE + - counters node + Description: Contains various non-volatile counters present in the platform. + + PROPERTIES + - id + Usage: Required for every nv-counter with unique id. + + Value type: <u32> + + - reg + Usage: + + Register base address of non-volatile counter and it is required + property. + + Value type: <u32> + + - oid + Usage: + + This property provides the Object ID of non-volatile counter + provided in the certificate and it is required property. + + Value type: <string> + +Example: +Below is non-volatile counters example for ARM platform + +.. code:: c + + non_volatile_counters: non_volatile_counters { + compatible = "arm, non-volatile-counter"; + #address-cells = <1>; + #size-cells = <0>; + + trusted-nv-counter: trusted_nv_counter { + id = <TRUSTED_NV_CTR_ID>; + reg = <TFW_NVCTR_BASE>; + oid = TRUSTED_FW_NVCOUNTER_OID; + }; + + non_trusted_nv_counter: non_trusted_nv_counter { + id = <NON_TRUSTED_NV_CTR_ID>; + reg = <NTFW_CTR_BASE>; + oid = NON_TRUSTED_FW_NVCOUNTER_OID; + }; + }; + +Future update to chain of trust binding +--------------------------------------- + +This binding document needs to be revisited to generalise some terminologies +which are currently specific to X.509 certificates for e.g. Object IDs. + +*Copyright (c) 2020, Arm Limited. All rights reserved.* |