diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst new file mode 100644 index 0000000..cc69d79 --- /dev/null +++ b/docs/components/cot-binding.rst @@ -0,0 +1,287 @@ +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. + +Convention used in this document +-------------------------------- + +This document follows the conventions described in the Device-tree +Specification + +certificates, certificate and extension node bindings definition +---------------------------------------------------------------- + +- Certificates node + Description: Container of certificate nodes. + + PROPERTIES + + - compatible: + Usage: required + + Value type: + + Definition: must be "arm, certificate-descriptors" + +- 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: + + - image-id + Usage: Required for every certificate with unique id. + + 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. + + This property is not required for root-certificates + as it is 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. + + 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. + + This property is used to refer trusted or non-trusted + non-volatile counter node. + + Value type: + + SUBNODES + + - 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 + + PROPERTIES + + - oid + Usage: This property provides the Object ID of an extension + provided in the certificate. + + Value type: + +Example: + +.. code:: c + + certificates { + compatible = "arm, certificate-descriptors” + + 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; + }; + }; + }; + + 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; + }; + }; + }; + + . + . + . + + next-cert { + + }; + }; + +Images and image node bindings definition +----------------------------------------- + +- Images node + Description: Container of image nodes + + PROPERTIES + + - compatible: + Usage: required + + Value type: + + Definition: must be "arm, image-descriptors" + +- 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: + + - parent + Usage: Required for every image to provide a reference to + it's 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. + + 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. + +Example: + +.. code:: c + + images { + compatible = "arm, imgage-descriptors"; + + scp_bl2_image { + 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: + + Definition: must be "arm, non-volatile-counter" + + - #address-cells + Usage: required + + Value type: + + Definition: Must be set according to address size + of non-volatile counter register + + - #size-cells + Usage: required + + Value type: + + Definition: must be set to 0 + + SUBNODE + - counters node + Description: Contains various non-volatile counters present in the platform. + + PROPERTIES + + - reg + 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. + + Value type: + +Example: +Below is non-volatile counters example for ARM platform + +.. code:: c + + non-volatile-counters { + compatible = "arm, non-volatile-counter"; + #address-cells = <1>; + #size-cells = <0>; + + counters { + trusted-nv-counter: trusted_nv_counter { + reg = ; + oid = TRUSTED_FW_NVCOUNTER_OID; + }; + non_trusted_nv_counter: non_trusted_nv_counter { + reg = ; + oid = NON_TRUSTED_FW_NVCOUNTER_OID; + + }; + }; + }; + +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. + +*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* diff --git a/docs/components/index.rst b/docs/components/index.rst index c5f6264..18b1e38 100644 --- a/docs/components/index.rst +++ b/docs/components/index.rst @@ -19,3 +19,4 @@ secure-partition-manager-design psa-ffa-manifest-binding xlat-tables-lib-v2-design + cot-binding