mirror of
https://github.com/CTCaer/switch-l4t-atf.git
synced 2024-11-30 13:20:22 +00:00
doc: Add a binding document for COT descriptors
Added a binding document for COT descriptors which is going to be used in order to create COT desciptors at run-time. Signed-off-by: Manish V Badarkhe <Manish.Badarkhe@arm.com> Change-Id: Ic54519b0e16d145cd1609274a00b137a9194e8dd
This commit is contained in:
Manish V Badarkhe
parent
3fbec43648
commit
ebd34bea0b
287
docs/components/cot-binding.rst
Normal file
287
docs/components/cot-binding.rst
Normal file
@ -0,0 +1,287 @@
|
||||
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.*
|
||||
@ -19,3 +19,4 @@ Components
|
||||
secure-partition-manager-design
|
||||
psa-ffa-manifest-binding
|
||||
xlat-tables-lib-v2-design
|
||||
cot-binding
|
||||
|
||||
Loading…
Reference in New Issue
Block a user