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

4.18.1. cot

This is root node which contains ‘manifests’ and ‘images’ as sub-nodes

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

      For non-root certificates, 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 all root-certificates. If omitted, the root certificate will be validated using the default platform ROTPK. If instead the root certificate needs validating using a different ROTPK, the signing-key property should provide a reference to the ROTPK node to use.

      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:

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 {

      };
   };
};

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

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 {

      };
   };
};

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

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;
     };
};

4.18.5. rot_keys node binding definition

  • rot_keys node

    Description: Contains root-of-trust keys for the root certificates.

    SUBNODES
    • Description:

      Root of trust key information present in the root certificates are shown by these nodes.

    • rot key node

      Description: Provide ROT key information in the certificate.

      PROPERTIES

      • oid

        Usage:

        This property provides the Object ID of ROT key provided in the certificate.

        Value type: <string>

Example: Below is rot_keys example for CCA platform

rot_keys {
     swd_rot_pk: swd_rot_pk {
        oid = SWD_ROT_PK_OID;
     };

     prot_pk: prot_pk {
        oid = PROT_PK_OID;
     };
};

4.18.6. 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-2024, Arm Limited. All rights reserved.