docs/components/cot-binding.rst

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

                - 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 {
        compatible = "arm, non-volatile-counter";
        #address-cells = <1>;
        #size-cells = <0>;

        counters {
            trusted-nv-counter: trusted_nv_counter {
                reg = <TFW_NVCTR_BASE>;
                oid = TRUSTED_FW_NVCOUNTER_OID;
            };
            non_trusted_nv_counter: non_trusted_nv_counter {
                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.*