8.6 KiB
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:
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:
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
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.