Merge "doc: Update CoT binding to make it more generic" into integration
diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst
index cc69d79..46915db 100644
--- a/docs/components/cot-binding.rst
+++ b/docs/components/cot-binding.rst
@@ -1,23 +1,23 @@
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.
+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.
-Convention used in this document
---------------------------------
+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.
-This document follows the conventions described in the Device-tree
-Specification
+cot
+------------------------------------------------------------------
+This is root node which contains 'manifests' and 'images' as sub-nodes
-certificates, certificate and extension node bindings definition
+
+Manifests and Certificate node bindings definition
----------------------------------------------------------------
-- Certificates node
+- Manifests node
Description: Container of certificate nodes.
PROPERTIES
@@ -27,20 +27,24 @@
Value type: <string>
- Definition: must be "arm, certificate-descriptors"
+ Definition: must be "arm, cert-descs"
- Certificate node
- Description: Describes certificate properties which are used
- during the authentication process.
+ 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.
+ Usage:
- Value type: <boolean>
+ 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.
@@ -48,99 +52,121 @@
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.
+ Usage:
- This property is not required for root-certificates
- as it is validated using root of trust public key
- provided by platform.
+ 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 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.
+ Usage:
- This property is not required for root-certificates
- as root-certificates are validated using root of trust
- public key provided by platform.
+ 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 optional property.
+ Usage:
- This property is used to refer trusted or non-trusted
- non-volatile counter node.
+ 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:
- - 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
+ Hash and public key information present in the certificate
+ are shown by these nodes.
- PROPERTIES
+ - public key node
+ Description: Provide public key information in the certificate.
- - oid
- Usage: This property provides the Object ID of an extension
- provided in the certificate.
+ PROPERTIES
+
+ - oid
+ Usage:
- Value type: <string>
+ 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
- certificates {
- compatible = "arm, certificate-descriptors”
+ 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>;
- 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;
- };
- };
- };
+ root-certificate;
+ image-id = <TRUSTED_KEY_CERT_ID>;
+ antirollback-counter = <&trusted_nv_counter>;
- 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;
- };
- };
- };
+ 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>;
- next-cert {
+ scp_fw_content_pk: scp_fw_content_pk {
+ oid = SCP_FW_CONTENT_CERT_PK_OID;
+ };
+ };
+ .
+ .
+ .
- };
+ next-certificate {
+
+ };
+ };
};
-Images and image node bindings definition
+Images and Image node bindings definition
-----------------------------------------
- Images node
@@ -153,11 +179,13 @@
Value type: <string>
- Definition: must be "arm, image-descriptors"
+ Definition: must be "arm, img-descs"
- Image node
- Description: Describes image properties which will be used during
- authentication process.
+ Description:
+
+ Describes image properties which will be used during
+ authentication process.
PROPERTIES
@@ -167,35 +195,41 @@
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.
+ 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 extension
- node present in parent certificate and it is required
- property for all images.
+ 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.
+ 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";
+ cot {
+ images {
+ compatible = "arm, img-descs";
scp_bl2_image {
- image-id = <SCP_BL2_IMAGE_ID>;
- parent = <&scp_fw_content_cert>;
- hash = <&scp_fw_hash>;
+ image-id = <SCP_BL2_IMAGE_ID>;
+ parent = <&scp_fw_content_cert>;
+ hash = <&scp_fw_hash>;
};
.
@@ -203,7 +237,9 @@
.
next-img {
+
};
+ };
};
non-volatile counter node binding definition
@@ -226,8 +262,10 @@
Value type: <u32>
+ Definition:
+
- Definition: Must be set according to address size
- of non-volatile counter register
+ Must be set according to address size
+ of non-volatile counter register
- #size-cells
Usage: required
@@ -243,14 +281,18 @@
PROPERTIES
- reg
- Usage: Register base address of non-volatile counter and it is required
- property.
+ 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.
+ Usage:
+
+ This property provides the Object ID of non-volatile counter
+ provided in the certificate and it is required property.
Value type: <string>
@@ -280,8 +322,7 @@
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.
+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 and Contributors. All rights reserved.*
+*Copyright (c) 2020, Arm Limited. All rights reserved.*