diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/components/fconf.rst | 67 | ||||
| -rw-r--r-- | docs/design/firmware-design.rst | 4 | ||||
| -rw-r--r-- | docs/design/trusted-board-boot-build.rst | 24 | ||||
| -rw-r--r-- | docs/design/trusted-board-boot.rst | 25 |
4 files changed, 83 insertions, 37 deletions
diff --git a/docs/components/fconf.rst b/docs/components/fconf.rst index cec3cebe4..385660083 100644 --- a/docs/components/fconf.rst +++ b/docs/components/fconf.rst @@ -28,29 +28,45 @@ Examples namespace can be: - (|TBBR|) Chain of Trust data: tbbr.cot.trusted_boot_fw_cert - (|TBBR|) dynamic configuration info: tbbr.dyn_config.disable_auth - Arm io policies: arm.io_policies.bl2_image +- GICv3 properties: hw_config.gicv3_config.gicr_base Properties can be accessed with the ``FCONF_GET_PROPERTY(a,b,property)`` macro. Defining properties ~~~~~~~~~~~~~~~~~~~ -Properties composing the |FCONF| have to be stored in C structures. If another -backing store is wanted to be used, the platform has to provide a ``populate()`` -function to fill the corresponding C structure. - -The ``populate()`` function must be registered to the |FCONF| framework with -the ``FCONF_REGISTER_POPULATOR()`` macro. This ensures that the function would -be called inside the generic ``fconf_populate()`` function during +Properties composing the |FCONF| have to be stored in C structures. If +properties originate from a different backend source such as a device tree, +then the platform has to provide a ``populate()`` function which essentially +captures the property and stores them into a corresponding |FCONF| based C +structure. + +Such a ``populate()`` function is usually platform specific and is associated +with a specific backend source. For example, a populator function which +captures the hardware topology of the platform from the HW_CONFIG device tree. +Hence each ``populate()`` function must be registered with a specific +``config_type`` identifier. It broadly represents a logical grouping of +configuration properties which is usually a device tree file. + +Example: + - TB_FW: properties related to trusted firmware such as IO policies, + base address of other DTBs, mbedtls heap info etc. + - HW_CONFIG: properties related to hardware configuration of the SoC + such as topology, GIC controller, PSCI hooks, CPU ID etc. + +Hence the ``populate()`` callback must be registered to the (|FCONF|) framework +with the ``FCONF_REGISTER_POPULATOR()`` macro. This ensures that the function +would be called inside the generic ``fconf_populate()`` function during initialization. :: - int fconf_populate_tbbr_dyn_config(uintptr_t config) + int fconf_populate_topology(uintptr_t config) { - /* read dtb and fill tbbr_dyn_config struct */ + /* read hw config dtb and fill soc_topology struct */ } - FCONF_REGISTER_POPULATOR(fconf_populate_tbbr_dyn_config); + FCONF_REGISTER_POPULATOR(HW_CONFIG, topology, fconf_populate_topology); Then, a wrapper has to be provided to match the ``FCONF_GET_PROPERTY()`` macro: @@ -60,7 +76,7 @@ Then, a wrapper has to be provided to match the ``FCONF_GET_PROPERTY()`` macro: #define FCONF_GET_PROPERTY(a,b,property) a##__##b##_getter(property) /* my specific getter */ - #define tbbr__dyn_config_getter(id) tbbr_dyn_config.id + #define hw_config__topology_getter(prop) soc_topology.prop This second level wrapper can be used to remap the ``FCONF_GET_PROPERTY()`` to anything appropriate: structure, array, function, etc.. @@ -80,6 +96,33 @@ Populating the properties Once a valid device tree is available, the ``fconf_populate(config)`` function can be used to fill the C data structure with the data from the config |DTB|. This function will call all the ``populate()`` callbacks which have been -registered with ``FCONF_REGISTER_POPULATOR()``. +registered with ``FCONF_REGISTER_POPULATOR()`` as described above. .. uml:: ../resources/diagrams/plantuml/fconf_bl2_populate.puml + +Namespace guidance +~~~~~~~~~~~~~~~~~~ + +As mentioned above, properties are logically grouped around namespaces and +sub-namespaces. The following concepts should be considered when adding new +properties/namespaces. +The framework differentiates two types of properties: + - Properties used inside common code. + - Properties used inside platform specific code. + +The first category applies to properties being part of the firmware and shared +across multiple platforms. They should be globally accessible and defined +inside the ``lib/fconf`` directory. The namespace must be chosen to reflect the +feature/data abstracted. +Example: + - |TBBR| related properties: tbbr.cot.bl2_id + - Dynamic configuration information: dyn_cfg.dtb_info.hw_config_id + +The second category should represent the majority of the properties defined +within the framework: Platform specific properties. They must be accessed only +within the platform API and are defined only inside the platform scope. The +namespace must contain the platform name under which the properties defined +belong. +Example: + - Arm io framework: arm.io_policies.bl31_id + diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 8297dc785..8e9dc38e4 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -1859,7 +1859,7 @@ BL image during boot. | BL2 | <<<<<<<<<<<<< | | |----------| <<<<<<<<<<<<< |----------------| | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| <<<<<<<<<<<<< |----------------| + | | <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL32 | | | +----------------+ | | @@ -1896,7 +1896,7 @@ BL image during boot. | BL2 | <<<<<<<<<<<<< | | |----------| <<<<<<<<<<<<< |----------------| | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| +----------------+ + | | +----------------+ 0x04001000 +----------+ | MHU | 0x04000000 +----------+ diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst index f5c8bc98c..dd61b61f5 100644 --- a/docs/design/trusted-board-boot-build.rst +++ b/docs/design/trusted-board-boot-build.rst @@ -32,25 +32,28 @@ images with support for these features: - ``TRUSTED_BOARD_BOOT=1`` - ``GENERATE_COT=1`` + By default, this will use the Chain of Trust described in the TBBR-client + document. To select a different one, use the ``COT`` build option. + In the case of Arm platforms, the location of the ROTPK hash must also be specified at build time. The following locations are currently supported (see ``ARM_ROTPK_LOCATION`` build option): - ``ARM_ROTPK_LOCATION=regs``: the ROTPK hash is obtained from the Trusted - root-key storage registers present in the platform. On Juno, this + root-key storage registers present in the platform. On Juno, these registers are read-only. On FVP Base and Cortex models, the registers - are read-only, but the value can be specified using the command line + are also read-only, but the value can be specified using the command line option ``bp.trusted_key_storage.public_key`` when launching the model. On Juno board, the default value corresponds to an ECDSA-SECP256R1 public key hash, whose private part is not currently available. - ``ARM_ROTPK_LOCATION=devel_rsa``: use the default hash located in - plat/arm/board/common/rotpk/arm_rotpk_rsa_sha256.bin. Enforce generation - of the new hash if ROT_KEY is specified. + ``plat/arm/board/common/rotpk/arm_rotpk_rsa_sha256.bin``. Enforce + generation of the new hash if ``ROT_KEY`` is specified. - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the default hash located in - plat/arm/board/common/rotpk/arm_rotpk_ecdsa_sha256.bin. Enforce generation - of the new hash if ROT_KEY is specified. + ``plat/arm/board/common/rotpk/arm_rotpk_ecdsa_sha256.bin``. Enforce + generation of the new hash if ``ROT_KEY`` is specified. Example of command line using RSA development keys: @@ -64,9 +67,8 @@ images with support for these features: all fip The result of this build will be the bl1.bin and the fip.bin binaries. This - FIP will include the certificates corresponding to the Chain of Trust - described in the TBBR-client document. These certificates can also be found - in the output build directory. + FIP will include the certificates corresponding to the selected Chain of + Trust. These certificates can also be found in the output build directory. #. The optional FWU_FIP contains any additional images to be loaded from Non-Volatile storage during the :ref:`Firmware Update (FWU)` process. To build the @@ -102,8 +104,8 @@ images with support for these features: The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries. Both the FIP and FWU_FIP will include the certificates corresponding to the - Chain of Trust described in the TBBR-client document. These certificates - can also be found in the output build directory. + selected Chain of Trust. These certificates can also be found in the output + build directory. -------------- diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index 4802c97f3..96cf24c0b 100644 --- a/docs/design/trusted-board-boot.rst +++ b/docs/design/trusted-board-boot.rst @@ -19,7 +19,9 @@ A Chain of Trust (CoT) starts with a set of implicitly trusted components. On the Arm development platforms, these components are: - A SHA-256 hash of the Root of Trust Public Key (ROTPK). It is stored in the - trusted root-key storage registers. + trusted root-key storage registers. Alternatively, a development ROTPK might + be used and its hash embedded into the BL1 and BL2 images (only for + development purposes). - The BL1 image, on the assumption that it resides in ROM so cannot be tampered with. @@ -32,17 +34,17 @@ essential information to establish the CoT. In the TBB CoT all certificates are self-signed. There is no need for a Certificate Authority (CA) because the CoT is not established by verifying the validity of a certificate's issuer but by the content of the certificate -extensions. To sign the certificates, the PKCS#1 SHA-256 with RSA Encryption -signature scheme is used with a RSA key length of 2048 bits. Future version of -TF-A will support additional cryptographic algorithms. +extensions. To sign the certificates, different signature schemes are available, +please refer to the :ref:`Build Options` for more details. The certificates are categorised as "Key" and "Content" certificates. Key certificates are used to verify public keys which have been used to sign content certificates. Content certificates are used to store the hash of a boot loader image. An image can be authenticated by calculating its hash and matching it -with the hash extracted from the content certificate. The SHA-256 function is -used to calculate all hashes. The public keys and hashes are included as -non-standard extension fields in the `X.509 v3`_ certificates. +with the hash extracted from the content certificate. Various hash algorithms +are supported to calculate all hashes, please refer to the :ref:`Build Options` +for more details.. The public keys and hashes are included as non-standard +extension fields in the `X.509 v3`_ certificates. The keys used to establish the CoT are: @@ -63,10 +65,10 @@ The keys used to establish the CoT are: non secure world image (BL33). The public part is stored in one of the extension fields in the trusted world certificate. -- **BL3-X keys** +- **BL3X keys** For each of SCP_BL2, BL31, BL32 and BL33, the private part is used to - sign the content certificate for the BL3-X image. The public part is stored + sign the content certificate for the BL3X image. The public part is stored in one of the extension fields in the corresponding key certificate. The following images are included in the CoT: @@ -219,8 +221,7 @@ certificates (in DER format) required to establish the CoT. New keys can be generated by the tool in case they are not provided. The certificates are then passed as inputs to the ``fiptool`` utility for creating the FIP. -The certificates are also stored individually in the in the output build -directory. +The certificates are also stored individually in the output build directory. The tool resides in the ``tools/cert_create`` directory. It uses the OpenSSL SSL library version to generate the X.509 certificates. The specific version of the @@ -259,7 +260,7 @@ Instructions for building and using the tool can be found in the -------------- -*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2015-2020, Arm Limited and Contributors. All rights reserved.* .. _X.509 v3: https://tools.ietf.org/rfc/rfc5280.txt .. _Trusted Board Boot Requirements (TBBR): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a |