Skip to content

GitLab

Commit 25311527 authored by Sandrine Bailleux's avatar Sandrine Bailleux Committed by TrustedFirmware Code Review
Browse files

Merge "doc: Update CoT binding to make it more generic" into integration

parents 946d5f67 b5fb6917
Hide whitespace changes
Inline Side-by-side
docs/components/cot-binding.rst
View file @ 25311527
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 @@ certificates, certificate and extension node bindings definition
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:
Required for the certificate with no parent.
In other words, certificates which are validated
using root of trust public key.
Value type: <boolean>
Value type: <boolean>
- image-id
Usage: Required for every certificate with unique id.
......@@ -48,99 +52,121 @@ certificates, certificate and extension node bindings definition
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 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.
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 @@ Images and image node bindings definition
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 @@ Images and image node bindings definition
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 @@ Example:
.
next-img {
};
};
};
non-volatile counter node binding definition
......@@ -226,8 +262,10 @@ non-volatile counter node binding definition
Value type: <u32>
Definition: Must be set according to address size
of non-volatile counter register
Definition:
Must be set according to address size
of non-volatile counter register
- #size-cells
Usage: required
......@@ -243,14 +281,18 @@ non-volatile counter node binding definition
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 @@ Below is non-volatile counters example for ARM platform
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.*
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment