diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst index cc69d79..46915db 100644 --- a/docs/components/cot-binding.rst +++ b/docs/components/cot-binding.rst @@ -1,23 +1,23 @@ Chain of trust bindings ======================= -The device tree allows to describes the chain of trust with the help of -certificates and images nodes, which in turn contains number of sub-nodes -(i.e. certificate and image) mentioning properties for every certificate -and image respectively. -Also, this binding allows to describe OID of non-volatile counters, memory -mapped address and size of non-volatile counter register. +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. -Convention used in this document --------------------------------- +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. -This document follows the conventions described in the Device-tree -Specification +cot +------------------------------------------------------------------ +This is root node which contains 'manifests' and 'images' as sub-nodes -certificates, certificate and extension node bindings definition + +Manifests and Certificate node bindings definition ---------------------------------------------------------------- -- Certificates node +- Manifests node Description: Container of certificate nodes. PROPERTIES @@ -27,20 +27,24 @@ Value type: - Definition: must be "arm, certificate-descriptors" + Definition: must be "arm, cert-descs" - Certificate node - Description: Describes certificate properties which are used - during the authentication process. + 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. + Usage: - Value type: + Required for the certificate with no parent. + In other words, certificates which are validated + using root of trust public key. + + Value type: - image-id Usage: Required for every certificate with unique id. @@ -48,99 +52,121 @@ Value type: - 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. + Usage: - This property is not required for root-certificates - as it is validated using root of trust public key - provided by platform. + 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: - signing-key - Usage: This property is used to refer extension node present in - parent certificate and it is required property for all non- - root certificates which are authenticated using public-key - present in parent certificate. + Usage: - This property is not required for root-certificates - as root-certificates are validated using root of trust - public key provided by platform. + 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: - antirollback-counter - Usage: This property is used by all certificates which are protected - against rollback attacks using a non-volatile counter and it - is optional property. + Usage: - This property is used to refer trusted or non-trusted - non-volatile counter node. + 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: + SUBNODES + - Description: - - extensions node - Description: This is sub-node of certificate node. - Describes OIDs present in the certificate which will - be used during authentication process to extract - hash/public key information from this certificate. - OIDs in extension node are represented using number of - sub-nodes which contains 'oid' as property + Hash and public key information present in the certificate + are shown by these nodes. - PROPERTIES + - public key node + Description: Provide public key information in the certificate. - - oid - Usage: This property provides the Object ID of an extension - provided in the certificate. + PROPERTIES - Value type: + - 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: + + - 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: Example: .. code:: c - certificates { - compatible = "arm, certificate-descriptors” + cot { + manifests { + compatible = "arm, cert-descs” trusted-key-cert: trusted-key-cert { - root-certificate; - image-id = ; - antirollback-counter = <&trusted_nv_counter>; - extensions { - 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; - }; - }; - }; + root-certificate; + image-id = ; + antirollback-counter = <&trusted_nv_counter>; - scp_fw_key_cert: scp_fw_key_cert { - image-id = ; - parent = <&trusted-key-cert>; - signing-key = <&trusted_world_pk>; - antirollback-counter = <&trusted_nv_counter>; - extensions { - scp_fw_content_pk: scp_fw_content_pk { - oid = SCP_FW_CONTENT_CERT_PK_OID; - }; - }; - }; + 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 = ; + parent = <&trusted-key-cert>; + signing-key = <&trusted_world_pk>; + antirollback-counter = <&trusted_nv_counter>; - next-cert { + scp_fw_content_pk: scp_fw_content_pk { + oid = SCP_FW_CONTENT_CERT_PK_OID; + }; + }; + . + . + . - }; + next-certificate { + + }; + }; }; -Images and image node bindings definition +Images and Image node bindings definition ----------------------------------------- - Images node @@ -153,11 +179,13 @@ Value type: - Definition: must be "arm, image-descriptors" + Definition: must be "arm, img-descs" - Image node - Description: Describes image properties which will be used during - authentication process. + Description: + + Describes image properties which will be used during + authentication process. PROPERTIES @@ -167,35 +195,41 @@ Value type: - parent - Usage: Required for every image to provide a reference to - it's parent image, which contains the necessary information - to authenticate it. + Usage: + + Required for every image to provide a reference to + its parent image, which contains the necessary information + to authenticate it. Value type: - hash - Usage: Required for all images which are validated using - hash method. This property is used to refer extension - node present in parent certificate and it is required - property for all images. + 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: - Note: Currently, all images are validated using "hash" - method. In future, there may be multiple methods can - be used to validate the image. + 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 - images { - compatible = "arm, imgage-descriptors"; + cot { + images { + compatible = "arm, img-descs"; scp_bl2_image { - image-id = ; - parent = <&scp_fw_content_cert>; - hash = <&scp_fw_hash>; + image-id = ; + parent = <&scp_fw_content_cert>; + hash = <&scp_fw_hash>; }; . @@ -203,7 +237,9 @@ . next-img { + }; + }; }; non-volatile counter node binding definition @@ -226,8 +262,10 @@ Value type: - Definition: Must be set according to address size - of non-volatile counter register + Definition: + + Must be set according to address size + of non-volatile counter register - #size-cells Usage: required @@ -243,14 +281,18 @@ PROPERTIES - reg - Usage: Register base address of non-volatile counter and it is required - property. + Usage: + + Register base address of non-volatile counter and it is required + property. Value type: - oid - Usage: This property provides the Object ID of non-volatile counter - provided in the certificate and it is required property. + Usage: + + This property provides the Object ID of non-volatile counter + provided in the certificate and it is required property. Value type: @@ -280,8 +322,7 @@ Future update to chain of trust binding --------------------------------------- -This binding document need to be revisited to generalise some terminologies -like Object IDs, extensions etc which are currently specific to X.509 -certificates. +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 and Contributors. All rights reserved.* +*Copyright (c) 2020, Arm Limited. All rights reserved.*