Merge "doc: Add a binding document for COT descriptors" into integration

docs/components/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.*

docs/components/index.rst

@@ -19,3 +19,4 @@ Components
    secure-partition-manager-design
    psa-ffa-manifest-binding
    xlat-tables-lib-v2-design
+   cot-binding