cot-binding.rst

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: <string>

                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: <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 it is validated using root of trust public key
                       provided by platform.

                Value type: <phandle>

        - 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: <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 optional property.

                       This property is used to refer trusted or non-trusted
                       non-volatile counter node.

                Value type: <phandle>

        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: <string>

Example:

.. code:: c

   certificates {
         compatible = "arm, certificate-descriptors”

         trusted-key-cert: trusted-key-cert {
                  root-certificate;
                  image-id = <TRUSTED_KEY_CERT_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 = <SCP_FW_KEY_CERT_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: <string>

                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: <u32>

        - 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: <phandle>

        - 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: <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

   images {
         compatible = "arm, imgage-descriptors";

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