From 16948ae1d9e14190229f0fd8602f8cc0f25d57d2 Mon Sep 17 00:00:00 2001 From: Juan Castillo Date: Mon, 13 Apr 2015 17:36:19 +0100 Subject: Use numbers to identify images instead of names The Trusted firmware code identifies BL images by name. The platform port defines a name for each image e.g. the IO framework uses this mechanism in the platform function plat_get_image_source(). For a given image name, it returns the handle to the image file which involves comparing images names. In addition, if the image is packaged in a FIP, a name comparison is required to find the UUID for the image. This method is not optimal. This patch changes the interface between the generic and platform code with regard to identifying images. The platform port must now allocate a unique number (ID) for every image. The generic code will use the image ID instead of the name to access its attributes. As a result, the plat_get_image_source() function now takes an image ID as an input parameter. The organisation of data structures within the IO framework has been rationalised to use an image ID as an index into an array which contains attributes of the image such as UUID and name. This prevents the name comparisons. A new type 'io_uuid_spec_t' has been introduced in the IO framework to specify images identified by UUID (i.e. when the image is contained in a FIP file). There is no longer need to maintain a look-up table [iname_name --> uuid] in the io_fip driver code. Because image names are no longer mandatory in the platform port, the debug messages in the generic code will show the image identifier instead of the file name. The platforms that support semihosting to load images (i.e. FVP) must provide the file names as definitions private to the platform. The ARM platform ports and documentation have been updated accordingly. All ARM platforms reuse the image IDs defined in the platform common code. These IDs will be used to access other attributes of an image in subsequent patches. IMPORTANT: applying this patch breaks compatibility for platforms that use TF BL1 or BL2 images or the image loading code. The platform port must be updated to match the new interface. Change-Id: I9c1b04cb1a0684c6ee65dee66146dd6731751ea5 --- docs/porting-guide.md | 143 ++++++++++++++++++++++++++------------------------ 1 file changed, 75 insertions(+), 68 deletions(-) (limited to 'docs/porting-guide.md') diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 436dc106..4f842c48 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -134,51 +134,6 @@ platform port to define additional platform porting constants in Defines the character string printed by BL1 upon entry into the `bl1_main()` function. -* **#define : BL2_IMAGE_NAME** - - Name of the BL2 binary image on the host file-system. This name is used by - BL1 to load BL2 into secure memory from non-volatile storage. - -* **#define : BL31_IMAGE_NAME** - - Name of the BL3-1 binary image on the host file-system. This name is used by - BL2 to load BL3-1 into secure memory from platform storage. - -* **#define : BL33_IMAGE_NAME** - - Name of the BL3-3 binary image on the host file-system. This name is used by - BL2 to load BL3-3 into non-secure memory from platform storage. - -* **#define : BL2_CERT_NAME** - - Name of the BL2 content certificate on the host file-system (mandatory when - Trusted Board Boot is enabled). - -* **#define : TRUSTED_KEY_CERT_NAME** - - Name of the Trusted Key certificate on the host file-system (mandatory when - Trusted Board Boot is enabled). - -* **#define : BL31_KEY_CERT_NAME** - - Name of the BL3-1 Key certificate on the host file-system (mandatory when - Trusted Board Boot is enabled). - -* **#define : BL31_CERT_NAME** - - Name of the BL3-1 Content certificate on the host file-system (mandatory - when Trusted Board Boot is enabled). - -* **#define : BL33_KEY_CERT_NAME** - - Name of the BL3-3 Key certificate on the host file-system (mandatory when - Trusted Board Boot is enabled). - -* **#define : BL33_CERT_NAME** - - Name of the BL3-3 Content certificate on the host file-system (mandatory - when Trusted Board Boot is enabled). - * **#define : PLATFORM_CORE_COUNT** Defines the total number of CPUs implemented by the platform across all @@ -243,42 +198,93 @@ platform port to define additional platform porting constants in Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary image. Must be aligned on a page-size boundary. +For every image, the platform must define individual identifiers that will be +used by BL1 or BL2 to load the corresponding image into memory from non-volatile +storage. For the sake of performance, integer numbers will be used as +identifiers. The platform will use those identifiers to return the relevant +information about the image to be loaded (file handler, load address, +authentication information, etc.). The following image identifiers are +mandatory: + +* **#define : BL2_IMAGE_ID** + + BL2 image identifier, used by BL1 to load BL2. + +* **#define : BL31_IMAGE_ID** + + BL3-1 image identifier, used by BL2 to load BL3-1. + +* **#define : BL33_IMAGE_ID** + + BL3-3 image identifier, used by BL2 to load BL3-3. + +If Trusted Board Boot is enabled, the following certificate identifiers must +also be defined: + +* **#define : BL2_CERT_ID** + + BL2 content certificate identifier, used by BL1 to load the BL2 content + certificate. + +* **#define : TRUSTED_KEY_CERT_ID** + + Trusted key certificate identifier, used by BL2 to load the trusted key + certificate. + +* **#define : BL31_KEY_CERT_ID** + + BL3-1 key certificate identifier, used by BL2 to load the BL3-1 key + certificate. + +* **#define : BL31_CERT_ID** + + BL3-1 content certificate identifier, used by BL2 to load the BL3-1 content + certificate. + +* **#define : BL33_KEY_CERT_ID** + + BL3-3 key certificate identifier, used by BL2 to load the BL3-3 key + certificate. + +* **#define : BL33_CERT_ID** + + BL3-3 content certificate identifier, used by BL2 to load the BL3-3 content + certificate. + If a BL3-0 image is supported by the platform, the following constants must also be defined: -* **#define : BL30_IMAGE_NAME** +* **#define : BL30_IMAGE_ID** - Name of the BL3-0 binary image on the host file-system. This name is used by - BL2 to load BL3-0 into secure memory from platform storage before being - transfered to the SCP. + BL3-0 image identifier, used by BL2 to load BL3-0 into secure memory from + platform storage before being transfered to the SCP. -* **#define : BL30_KEY_CERT_NAME** +* **#define : BL30_KEY_CERT_ID** - Name of the BL3-0 Key certificate on the host file-system (mandatory when - Trusted Board Boot is enabled). + BL3-0 key certificate identifier, used by BL2 to load the BL3-0 key + certificate (mandatory when Trusted Board Boot is enabled). -* **#define : BL30_CERT_NAME** +* **#define : BL30_CERT_ID** - Name of the BL3-0 Content certificate on the host file-system (mandatory - when Trusted Board Boot is enabled). + BL3-0 content certificate identifier, used by BL2 to load the BL3-0 content + certificate (mandatory when Trusted Board Boot is enabled). If a BL3-2 image is supported by the platform, the following constants must also be defined: -* **#define : BL32_IMAGE_NAME** +* **#define : BL32_IMAGE_ID** - Name of the BL3-2 binary image on the host file-system. This name is used by - BL2 to load BL3-2 into secure memory from platform storage. + BL3-2 image identifier, used by BL2 to load BL3-2. -* **#define : BL32_KEY_CERT_NAME** +* **#define : BL32_KEY_CERT_ID** - Name of the BL3-2 Key certificate on the host file-system (mandatory when - Trusted Board Boot is enabled). + BL3-2 key certificate identifier, used by BL2 to load the BL3-2 key + certificate (mandatory when Trusted Board Boot is enabled). -* **#define : BL32_CERT_NAME** +* **#define : BL32_CERT_ID** - Name of the BL3-2 Content certificate on the host file-system (mandatory - when Trusted Board Boot is enabled). + BL3-2 content certificate identifier, used by BL2 to load the BL3-2 content + certificate (mandatory when Trusted Board Boot is enabled). * **#define : BL32_BASE** @@ -1528,10 +1534,11 @@ provide at least one driver for a device capable of supporting generic operations such as loading a bootloader image. The current implementation only allows for known images to be loaded by the -firmware. These images are specified by using their names, as defined in -[include/plat/common/platform.h]. The platform layer (`plat_get_image_source()`) -then returns a reference to a device and a driver-specific `spec` which will be -understood by the driver to allow access to the image data. +firmware. These images are specified by using their identifiers, as defined in +[include/plat/common/platform_def.h] (or a separate header file included from +there). The platform layer (`plat_get_image_source()`) then returns a reference +to a device and a driver-specific `spec` which will be understood by the driver +to allow access to the image data. The layer is designed in such a way that is it possible to chain drivers with other drivers. For example, file-system drivers may be implemented on top of -- cgit From 95cfd4ad84633502938a8bccc2b0290dfbcac2f7 Mon Sep 17 00:00:00 2001 From: Juan Castillo Date: Tue, 14 Apr 2015 12:49:03 +0100 Subject: TBB: add platform API to read the ROTPK information This patch extends the platform port by adding an API that returns either the Root of Trust public key (ROTPK) or its hash. This is usually stored in ROM or eFUSE memory. The ROTPK returned must be encoded in DER format according to the following ASN.1 structure: SubjectPublicKeyInfo ::= SEQUENCE { algorithm AlgorithmIdentifier, subjectPublicKey BIT STRING } In case the platform returns a hash of the key: DigestInfo ::= SEQUENCE { digestAlgorithm AlgorithmIdentifier, keyDigest OCTET STRING } An implementation for ARM development platforms is provided in this patch. When TBB is enabled, the ROTPK hash location must be specified using the build option 'ARM_ROTPK_LOCATION'. Available options are: - 'regs' : return the ROTPK hash stored in the Trusted root-key storage registers. - 'devel_rsa' : return a ROTPK hash embedded in the BL1 and BL2 binaries. This hash has been obtained from the development RSA public key located in 'plat/arm/board/common/rotpk'. On FVP, the number of MMU tables has been increased to map and access the ROTPK registers. A new file 'board_common.mk' has been added to improve code sharing in the ARM develelopment platforms. Change-Id: Ib25862e5507d1438da10773e62bd338da8f360bf --- docs/porting-guide.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) (limited to 'docs/porting-guide.md') diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 4f842c48..d0096054 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -483,6 +483,38 @@ returns 0 (success) if that key matches the ROT (Root Of Trust) key stored in the platform. Any other return value means a mismatch. +### Function: plat_get_rotpk_info() + + Argument : void *, void **, unsigned int *, unsigned int * + Return : int + +This function is mandatory when Trusted Board Boot is enabled. It returns a +pointer to the ROTPK stored in the platform (or a hash of it) and its length. +The ROTPK must be encoded in DER format according to the following ASN.1 +structure: + + AlgorithmIdentifier ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters ANY DEFINED BY algorithm OPTIONAL + } + + SubjectPublicKeyInfo ::= SEQUENCE { + algorithm AlgorithmIdentifier, + subjectPublicKey BIT STRING + } + +In case the function returns a hash of the key: + + DigestInfo ::= SEQUENCE { + digestAlgorithm AlgorithmIdentifier, + digest OCTET STRING + } + +The function returns 0 on success. Any other value means the ROTPK could not be +retrieved from the platform. The function also reports extra information related +to the ROTPK in the flags parameter. + + 2.3 Common optional modifications --------------------------------- -- cgit From f04585f399865fb12a53b0c332807387adb7cb2f Mon Sep 17 00:00:00 2001 From: Juan Castillo Date: Fri, 10 Apr 2015 12:43:27 +0100 Subject: TBB: delete deprecated plat_match_rotpk() The authentication framework deprecates plat_match_rotpk() in favour of plat_get_rotpk_info(). This patch removes plat_match_rotpk() from the platform port. Change-Id: I2250463923d3ef15496f9c39678b01ee4b33883b --- docs/porting-guide.md | 11 ----------- 1 file changed, 11 deletions(-) (limited to 'docs/porting-guide.md') diff --git a/docs/porting-guide.md b/docs/porting-guide.md index d0096054..2f013535 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -472,17 +472,6 @@ The ARM FVP port uses this function to initialize the mailbox memory used for providing the warm-boot entry-point addresses. -### Function: plat_match_rotpk() - - Argument : const unsigned char *, unsigned int - Return : int - -This function is mandatory when Trusted Board Boot is enabled. It receives a -pointer to a buffer containing a signing key and its size as parameters and -returns 0 (success) if that key matches the ROT (Root Of Trust) key stored in -the platform. Any other return value means a mismatch. - - ### Function: plat_get_rotpk_info() Argument : void *, void **, unsigned int *, unsigned int * -- cgit