andrius
/
arm-trusted-firmware
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

doc: Update CoT binding to make it more generic 

Updated the CoT binding document to show chain of trust relationship
with the help of 'authentication method' and 'authentication data'
instead of showing content of certificate and fixed rendering issue
while creating html page using this document.

Signed-off-by: Manish V Badarkhe <Manish.Badarkhe@arm.com>
Change-Id: Ib48279cfe786d149ab69ddc711caa381a50f9e2b
This commit is contained in:
Manish V Badarkhe 2020-06-30 04:04:05 +01:00
parent 2634ef6d79
commit b5fb69173b
1 changed files with 149 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

257
docs/components/cot-binding.rst
View File

@ -1,23 +1,23 @@
Chain of trust bindings Chain of trust bindings
======================= =======================
The device tree allows to describes the chain of trust with the help of The device tree allows to describe the chain of trust with the help of
certificates and images nodes, which in turn contains number of sub-nodes 'cot' node which contain 'manifests' and 'images' as sub-nodes.
(i.e. certificate and image) mentioning properties for every certificate 'manifests' and 'images' nodes contains number of sub-nodes (i.e. 'certificate'
and image respectively. and 'image' nodes) mentioning properties of the 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 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 cot
Specification ------------------------------------------------------------------
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. Description: Container of certificate nodes.
PROPERTIES PROPERTIES
@ -27,20 +27,24 @@ certificates, certificate and extension node bindings definition
Value type: <string> Value type: <string>
Definition: must be "arm, certificate-descriptors" Definition: must be "arm, cert-descs"
- Certificate node - Certificate node
Description: Describes certificate properties which are used Description:
during the authentication process.
Describes certificate properties which are used
during the authentication process.
PROPERTIES PROPERTIES
- root-certificate - root-certificate
Usage: Required for the certificate with no parent. Usage:
In other words, Certificates which are validated
using root of trust public key.
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 - image-id
Usage: Required for every certificate with unique id. Usage: Required for every certificate with unique id.
@ -48,99 +52,121 @@ certificates, certificate and extension node bindings definition
Value type: <u32> Value type: <u32>
- parent - parent
Usage: It refers to their parent image, which typically contains Usage:
information to authenticate the certificate.
This property is required for all non-root certificates.
This property is not required for root-certificates It refers to their parent image, which typically contains
as it is validated using root of trust public key information to authenticate the certificate.
provided by platform. 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> Value type: <phandle>
- signing-key - signing-key
Usage: This property is used to refer extension node present in Usage:
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 This property is used to refer public key node present in
as root-certificates are validated using root of trust parent certificate node and it is required property for all
public key provided by platform. 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> Value type: <phandle>
- antirollback-counter - antirollback-counter
Usage: This property is used by all certificates which are protected Usage:
against rollback attacks using a non-volatile counter and it
is optional property.
This property is used to refer trusted or non-trusted This property is used by all certificates which are
non-volatile counter node. 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> Value type: <phandle>
SUBNODES SUBNODES
- Description:
- extensions node Hash and public key information present in the certificate
Description: This is sub-node of certificate node. are shown by these nodes.
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 - public key node
Description: Provide public key information in the certificate.
- oid PROPERTIES
Usage: This property provides the Object ID of an extension
provided in the certificate.
Value type: <string> - 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: Example:
.. code:: c .. code:: c
certificates { cot {
compatible = "arm, certificate-descriptors” manifests {
compatible = "arm, cert-descs”
trusted-key-cert: trusted-key-cert { trusted-key-cert: trusted-key-cert {
root-certificate; root-certificate;
image-id = <TRUSTED_KEY_CERT_ID>; image-id = <TRUSTED_KEY_CERT_ID>;
antirollback-counter = <&trusted_nv_counter>; 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 { trusted-world-pk: trusted-world-pk {
image-id = <SCP_FW_KEY_CERT_ID>; oid = TRUSTED_WORLD_PK_OID;
parent = <&trusted-key-cert>; };
signing-key = <&trusted_world_pk>; non-trusted-world-pk: non-trusted-world-pk {
antirollback-counter = <&trusted_nv_counter>; oid = NON_TRUSTED_WORLD_PK_OID;
extensions { };
scp_fw_content_pk: scp_fw_content_pk { };
oid = SCP_FW_CONTENT_CERT_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 - Images node
@ -153,11 +179,13 @@ Images and image node bindings definition
Value type: <string> Value type: <string>
Definition: must be "arm, image-descriptors" Definition: must be "arm, img-descs"
- Image node - Image node
Description: Describes image properties which will be used during Description:
authentication process.
Describes image properties which will be used during
authentication process.
PROPERTIES PROPERTIES
@ -167,35 +195,41 @@ Images and image node bindings definition
Value type: <u32> Value type: <u32>
- parent - parent
Usage: Required for every image to provide a reference to Usage:
it's parent image, which contains the necessary information
to authenticate it. Required for every image to provide a reference to
its parent image, which contains the necessary information
to authenticate it.
Value type: <phandle> Value type: <phandle>
- hash - hash
Usage: Required for all images which are validated using Usage:
hash method. This property is used to refer extension
node present in parent certificate and it is required Required for all images which are validated using
property for all images. hash method. This property is used to refer hash
node present in parent certificate node.
Value type: <phandle> Value type: <phandle>
Note: Currently, all images are validated using "hash" Note:
method. In future, there may be multiple methods can
be used to validate the image. Currently, all images are validated using 'hash'
method. In future, there may be multiple methods can
be used to validate the image.
Example: Example:
.. code:: c .. code:: c
images { cot {
compatible = "arm, imgage-descriptors"; images {
compatible = "arm, img-descs";
scp_bl2_image { scp_bl2_image {
image-id = <SCP_BL2_IMAGE_ID>; image-id = <SCP_BL2_IMAGE_ID>;
parent = <&scp_fw_content_cert>; parent = <&scp_fw_content_cert>;
hash = <&scp_fw_hash>; hash = <&scp_fw_hash>;
}; };
. .
@ -203,7 +237,9 @@ Example:
. .
next-img { next-img {
}; };
};
}; };
non-volatile counter node binding definition non-volatile counter node binding definition
@ -226,8 +262,10 @@ non-volatile counter node binding definition
Value type: <u32> Value type: <u32>
Definition: Must be set according to address size Definition:
of non-volatile counter register
Must be set according to address size
of non-volatile counter register
- #size-cells - #size-cells
Usage: required Usage: required
@ -243,14 +281,18 @@ non-volatile counter node binding definition
PROPERTIES PROPERTIES
- reg - reg
Usage: Register base address of non-volatile counter and it is required Usage:
property.
Register base address of non-volatile counter and it is required
property.
Value type: <u32> Value type: <u32>
- oid - oid
Usage: This property provides the Object ID of non-volatile counter Usage:
provided in the certificate and it is required property.
This property provides the Object ID of non-volatile counter
provided in the certificate and it is required property.
Value type: <string> Value type: <string>
@ -280,8 +322,7 @@ Below is non-volatile counters example for ARM platform
Future update to chain of trust binding Future update to chain of trust binding
--------------------------------------- ---------------------------------------
This binding document need to be revisited to generalise some terminologies This binding document needs to be revisited to generalise some terminologies
like Object IDs, extensions etc which are currently specific to X.509 which are currently specific to X.509 certificates for e.g. Object IDs.
certificates.
*Copyright (c) 2020, Arm Limited and Contributors. All rights reserved.* *Copyright (c) 2020, Arm Limited. All rights reserved.*