diff options
Diffstat (limited to 'docs/design')
| -rw-r--r-- | docs/design/auth-framework.rst | 50 | ||||
| -rw-r--r-- | docs/design/cpu-specific-build-macros.rst | 66 | ||||
| -rw-r--r-- | docs/design/firmware-design.rst | 215 | ||||
| -rw-r--r-- | docs/design/interrupt-framework-design.rst | 24 | ||||
| -rw-r--r-- | docs/design/trusted-board-boot-build.rst | 37 | ||||
| -rw-r--r-- | docs/design/trusted-board-boot.rst | 53 |
6 files changed, 285 insertions, 160 deletions
diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst index 93f691b7b..6913e66e1 100644 --- a/docs/design/auth-framework.rst +++ b/docs/design/auth-framework.rst @@ -619,11 +619,13 @@ recommended to read this guide along with the source code. The TBBR CoT ~~~~~~~~~~~~ -The CoT can be found in ``drivers/auth/tbbr/tbbr_cot.c``. This CoT consists of -an array of pointers to image descriptors and it is registered in the framework -using the macro ``REGISTER_COT(cot_desc)``, where 'cot_desc' must be the name -of the array (passing a pointer or any other type of indirection will cause the -registration process to fail). +CoT specific to BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_bl1.c`` +and ``drivers/auth/tbbr/tbbr_cot_bl2.c`` respectively. The common CoT used across +BL1 and BL2 can be found in ``drivers/auth/tbbr/tbbr_cot_common.c``. +This CoT consists of an array of pointers to image descriptors and it is +registered in the framework using the macro ``REGISTER_COT(cot_desc)``, where +``cot_desc`` must be the name of the array (passing a pointer or any other +type of indirection will cause the registration process to fail). The number of images participating in the boot process depends on the CoT. There is, however, a minimum set of images that are mandatory in TF-A and thus @@ -702,7 +704,7 @@ Each image descriptor must specify: address/size to store the parameter. The CoT is responsible for allocating the required memory to store the parameters. This pointer may be NULL. -In the ``tbbr_cot.c`` file, a set of buffers are allocated to store the parameters +In the ``tbbr_cot*.c`` file, a set of buffers are allocated to store the parameters extracted from the certificates. In the case of the TBBR CoT, these parameters are hashes and public keys. In DER format, an RSA-4096 public key requires 550 bytes, and a hash requires 51 bytes. Depending on the CoT and the authentication @@ -870,32 +872,32 @@ Once the signature has been checked and the certificate authenticated, the Trusted World public key needs to be extracted from the certificate. A new entry is created in the ``authenticated_data`` array for that purpose. In that entry, the corresponding parameter descriptor must be specified along with the buffer -address to store the parameter value. In this case, the ``tz_world_pk`` descriptor -is used to extract the public key from an x509v3 extension with OID +address to store the parameter value. In this case, the ``trusted_world_pk`` +descriptor is used to extract the public key from an x509v3 extension with OID ``TRUSTED_WORLD_PK_OID``. The BL31 key certificate will use this descriptor as parameter in the signature authentication method. The key is stored in the -``plat_tz_world_pk_buf`` buffer. +``trusted_world_pk_buf`` buffer. The **BL31 Key certificate** is authenticated by checking its digital signature using the Trusted World public key obtained previously from the Trusted Key certificate. In the image descriptor, we specify a single authentication method -by signature whose public key is the ``tz_world_pk``. Once this certificate has -been authenticated, we have to extract the BL31 public key, stored in the -extension specified by ``bl31_content_pk``. This key will be copied to the -``plat_content_pk`` buffer. +by signature whose public key is the ``trusted_world_pk``. Once this certificate +has been authenticated, we have to extract the BL31 public key, stored in the +extension specified by ``soc_fw_content_pk``. This key will be copied to the +``content_pk_buf`` buffer. The **BL31 certificate** is authenticated by checking its digital signature using the BL31 public key obtained previously from the BL31 Key certificate. -We specify the authentication method using ``bl31_content_pk`` as public key. +We specify the authentication method using ``soc_fw_content_pk`` as public key. After authentication, we need to extract the BL31 hash, stored in the extension -specified by ``bl31_hash``. This hash will be copied to the ``plat_bl31_hash_buf`` -buffer. +specified by ``soc_fw_hash``. This hash will be copied to the +``soc_fw_hash_buf`` buffer. The **BL31 image** is authenticated by calculating its hash and matching it with the hash obtained from the BL31 certificate. The image descriptor contains a single authentication method by hash. The parameters to the hash method are -the reference hash, ``bl31_hash``, and the data to be hashed. In this case, it is -the whole image, so we specify ``raw_data``. +the reference hash, ``soc_fw_hash``, and the data to be hashed. In this case, +it is the whole image, so we specify ``raw_data``. The image parser library ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -934,7 +936,7 @@ i.e. verify a hash or a digital signature. Arm platforms will use a library based on mbed TLS, which can be found in ``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports -three functions: +four functions: .. code:: c @@ -945,6 +947,11 @@ three functions: void *pk_ptr, unsigned int pk_len); int verify_hash(void *data_ptr, unsigned int data_len, void *digest_info_ptr, unsigned int digest_info_len); + int auth_decrypt(enum crypto_dec_algo dec_algo, void *data_ptr, + size_t len, const void *key, unsigned int key_len, + unsigned int key_flags, const void *iv, + unsigned int iv_len, const void *tag, + unsigned int tag_len) The mbedTLS library algorithm support is configured by both the ``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables. @@ -957,6 +964,9 @@ The mbedTLS library algorithm support is configured by both the - ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values include 1024, 2048, 3072 and 4096. +- ``TF_MBEDTLS_USE_AES_GCM`` enables the authenticated decryption support based + on AES-GCM algorithm. Valid values are 0 and 1. + .. note:: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can be defined in the platform Makefile. It will make mbed TLS use an @@ -965,6 +975,6 @@ The mbedTLS library algorithm support is configured by both the -------------- -*Copyright (c) 2017-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2017-2020, Arm Limited and Contributors. All rights reserved.* .. _TBBR-Client specification: https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a diff --git a/docs/design/cpu-specific-build-macros.rst b/docs/design/cpu-specific-build-macros.rst index f3096b418..7c142d132 100644 --- a/docs/design/cpu-specific-build-macros.rst +++ b/docs/design/cpu-specific-build-macros.rst @@ -127,6 +127,9 @@ For Cortex-A53, the following errata build flags are defined : Earlier revisions of the CPU have other errata which require the same workaround in software, so they should be covered anyway. +- ``ERRATA_A53_1530924``: This applies errata 1530924 workaround to all + revisions of Cortex-A53 CPU. + For Cortex-A55, the following errata build flags are defined : - ``ERRATA_A55_768277``: This applies errata 768277 workaround to Cortex-A55 @@ -147,6 +150,9 @@ For Cortex-A55, the following errata build flags are defined : - ``ERRATA_A55_1221012``: This applies errata 1221012 workaround to Cortex-A55 CPU. This needs to be enabled only for revision <= r1p0 of the CPU. +- ``ERRATA_A55_1530923``: This applies errata 1530923 workaround to all + revisions of Cortex-A55 CPU. + For Cortex-A57, the following errata build flags are defined : - ``ERRATA_A57_806969``: This applies errata 806969 workaround to Cortex-A57 @@ -182,12 +188,17 @@ For Cortex-A57, the following errata build flags are defined : - ``ERRATA_A57_859972``: This applies errata 859972 workaround to Cortex-A57 CPU. This needs to be enabled only for revision <= r1p3 of the CPU. +- ``ERRATA_A57_1319537``: This applies errata 1319537 workaround to all + revisions of Cortex-A57 CPU. For Cortex-A72, the following errata build flags are defined : - ``ERRATA_A72_859971``: This applies errata 859971 workaround to Cortex-A72 CPU. This needs to be enabled only for revision <= r0p3 of the CPU. +- ``ERRATA_A72_1319367``: This applies errata 1319367 workaround to all + revisions of Cortex-A72 CPU. + For Cortex-A73, the following errata build flags are defined : - ``ERRATA_A73_852427``: This applies errata 852427 workaround to Cortex-A73 @@ -227,11 +238,39 @@ For Cortex-A76, the following errata build flags are defined : - ``ERRATA_A76_1275112``: This applies errata 1275112 workaround to Cortex-A76 CPU. This needs to be enabled only for revision <= r3p0 of the CPU. -For Hercules, the following errata build flags are defined : +- ``ERRATA_A76_1791580``: This applies errata 1791580 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r4p0 of the CPU. + +- ``ERRATA_A76_1165522``: This applies errata 1165522 workaround to all + revisions of Cortex-A76 CPU. This errata is fixed in r3p0 but due to + limitation of errata framework this errata is applied to all revisions + of Cortex-A76 CPU. + +- ``ERRATA_A76_1868343``: This applies errata 1868343 workaround to Cortex-A76 + CPU. This needs to be enabled only for revision <= r4p0 of the CPU. -- ``ERRATA_HERCULES_1688305``: This applies errata 1688305 workaround to - Hercules CPU. This needs to be enabled only for revision r0p0 - r1p0 of - the CPU. +- ``ERRATA_A76_1946160``: This applies errata 1946160 workaround to Cortex-A76 + CPU. This needs to be enabled only for revisions r3p0 - r4p1 of the CPU. + +For Cortex-A77, the following errata build flags are defined : + +- ``ERRATA_A77_1508412``: This applies errata 1508412 workaround to Cortex-A77 + CPU. This needs to be enabled only for revision <= r1p0 of the CPU. + +- ``ERRATA_A77_1925769``: This applies errata 1925769 workaround to Cortex-A77 + CPU. This needs to be enabled only for revision <= r1p1 of the CPU. + +For Cortex-A78, the following errata build flags are defined : + +- ``ERRATA_A78_1688305``: This applies errata 1688305 workaround to Cortex-A78 + CPU. This needs to be enabled only for revision r0p0 - r1p0 of the CPU. + +- ``ERRATA_A78_1941498``: This applies errata 1941498 workaround to Cortex-A78 + CPU. This needs to be enabled for revisions r0p0, r1p0, and r1p1 of the CPU. + +- ``ERRATA_A78_1951500``: This applies errata 1951500 workaround to Cortex-A78 + CPU. This needs to be enabled for revisions r1p0 and r1p1, r0p0 has the same + issue but there is no workaround for that revision. For Neoverse N1, the following errata build flags are defined : @@ -268,6 +307,13 @@ For Neoverse N1, the following errata build flags are defined : - ``ERRATA_N1_1542419``: This applies errata 1542419 workaround to Neoverse-N1 CPU. This needs to be enabled only for revisions r3p0 - r4p0 of the CPU. +- ``ERRATA_N1_1868343``: This applies errata 1868343 workaround to Neoverse-N1 + CPU. This needs to be enabled only for revision <= r4p0 of the CPU. + +- ``ERRATA_N1_1946160``: This applies errata 1946160 workaround to Neoverse-N1 + CPU. This needs to be enabled for revisions r3p0, r3p1, r4p0, and r4p1, for + revisions r0p0, r1p0, and r2p0 there is no workaround. + DSU Errata Workarounds ---------------------- @@ -324,14 +370,22 @@ architecture that can be enabled by the platform as desired. as recommended in section "4.7 Non-Temporal Loads/Stores" of the `Cortex-A57 Software Optimization Guide`_. -- ``NEOVERSE_N1_EXTERNAL_LLC``: This flag indicates that an external last +- ''A57_ENABLE_NON_CACHEABLE_LOAD_FWD'': This flag enables non-cacheable + streaming enhancement feature for Cortex-A57 CPUs. Platforms can set + this bit only if their memory system meets the requirement that cache + line fill requests from the Cortex-A57 processor are atomic. Each + Cortex-A57 based platform must make its own decision on whether to use + the optimization. This flag is disabled by default. + +- ``NEOVERSE_Nx_EXTERNAL_LLC``: This flag indicates that an external last level cache(LLC) is present in the system, and that the DataSource field on the master CHI interface indicates when data is returned from the LLC. This is used to control how the LL_CACHE* PMU events count. + Default value is 0 (Disabled). -------------- -*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2020, Arm Limited and Contributors. All rights reserved.* .. _CVE-2017-5715: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715 .. _CVE-2018-3639: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639 diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst index 5fc1335b3..c12e73f45 100644 --- a/docs/design/firmware-design.rst +++ b/docs/design/firmware-design.rst @@ -83,6 +83,10 @@ Each of the Boot Loader stages may be dynamically configured if required by the platform. The Boot Loader stage may optionally specify a firmware configuration file and/or hardware configuration file as listed below: +- FW_CONFIG - The firmware configuration file. Holds properties shared across + all BLx images. + An example is the "dtb-registry" node, which contains the information about + the other device tree configurations (load-address, size, image_id). - HW_CONFIG - The hardware configuration file. Can be shared by all Boot Loader stages and also by the Normal World Rich OS. - TB_FW_CONFIG - Trusted Boot Firmware configuration file. Shared between BL1 @@ -109,8 +113,8 @@ convention: the generic hardware configuration is passed the next available argument. For example, - - If TB_FW_CONFIG is loaded by BL1, then its address is passed in ``arg0`` - to BL2. + - FW_CONFIG is loaded by BL1, then its address is passed in ``arg0`` to BL2. + - TB_FW_CONFIG address is retrieved by BL2 from FW_CONFIG device tree. - If HW_CONFIG is loaded by BL1, then its address is passed in ``arg2`` to BL2. Note, ``arg1`` is already used for meminfo_t. - If SOC_FW_CONFIG is loaded by BL2, then its address is passed in ``arg1`` @@ -365,7 +369,7 @@ Architectural initialization For AArch64, BL2 performs the minimal architectural initialization required for subsequent stages of TF-A and normal world software. EL1 and EL0 are given -access to Floating Point and Advanced SIMD registers by clearing the +access to Floating Point and Advanced SIMD registers by setting the ``CPACR.FPEN`` bits. For AArch32, the minimal architectural initialization required for subsequent @@ -544,7 +548,7 @@ It then replaces the exception vectors populated by BL1 with its own. BL31 exception vectors implement more elaborate support for handling SMCs since this is the only mechanism to access the runtime services implemented by BL31 (PSCI for example). BL31 checks each SMC for validity as specified by the -`SMC Calling Convention PDD`_ before passing control to the required SMC +`SMC Calling Convention`_ before passing control to the required SMC handler routine. BL31 programs the ``CNTFRQ_EL0`` register with the clock frequency of the system @@ -953,6 +957,8 @@ Function ID call type and OEN onto a specific service handler in the |Image 1| +.. _handling-an-smc: + Handling an SMC ~~~~~~~~~~~~~~~ @@ -984,7 +990,7 @@ before restoring the stack and CPU state and returning from the original SMC. Exception Handling Framework ---------------------------- -Please refer to the `Exception Handling Framework`_ document. +Please refer to the :ref:`Exception Handling Framework` document. Power State Coordination Interface ---------------------------------- @@ -1177,83 +1183,104 @@ The sample crash output is shown below. :: - x0 :0x000000004F00007C - x1 :0x0000000007FFFFFF - x2 :0x0000000004014D50 - x3 :0x0000000000000000 - x4 :0x0000000088007998 - x5 :0x00000000001343AC - x6 :0x0000000000000016 - x7 :0x00000000000B8A38 - x8 :0x00000000001343AC - x9 :0x00000000000101A8 - x10 :0x0000000000000002 - x11 :0x000000000000011C - x12 :0x00000000FEFDC644 - x13 :0x00000000FED93FFC - x14 :0x0000000000247950 - x15 :0x00000000000007A2 - x16 :0x00000000000007A4 - x17 :0x0000000000247950 - x18 :0x0000000000000000 - x19 :0x00000000FFFFFFFF - x20 :0x0000000004014D50 - x21 :0x000000000400A38C - x22 :0x0000000000247950 - x23 :0x0000000000000010 - x24 :0x0000000000000024 - x25 :0x00000000FEFDC868 - x26 :0x00000000FEFDC86A - x27 :0x00000000019EDEDC - x28 :0x000000000A7CFDAA - x29 :0x0000000004010780 - x30 :0x000000000400F004 - scr_el3 :0x0000000000000D3D - sctlr_el3 :0x0000000000C8181F - cptr_el3 :0x0000000000000000 - tcr_el3 :0x0000000080803520 - daif :0x00000000000003C0 - mair_el3 :0x00000000000004FF - spsr_el3 :0x00000000800003CC - elr_el3 :0x000000000400C0CC - ttbr0_el3 :0x00000000040172A0 - esr_el3 :0x0000000096000210 - sp_el3 :0x0000000004014D50 - far_el3 :0x000000004F00007C - spsr_el1 :0x0000000000000000 - elr_el1 :0x0000000000000000 - spsr_abt :0x0000000000000000 - spsr_und :0x0000000000000000 - spsr_irq :0x0000000000000000 - spsr_fiq :0x0000000000000000 - sctlr_el1 :0x0000000030C81807 - actlr_el1 :0x0000000000000000 - cpacr_el1 :0x0000000000300000 - csselr_el1 :0x0000000000000002 - sp_el1 :0x0000000004028800 - esr_el1 :0x0000000000000000 - ttbr0_el1 :0x000000000402C200 - ttbr1_el1 :0x0000000000000000 - mair_el1 :0x00000000000004FF - amair_el1 :0x0000000000000000 - tcr_el1 :0x0000000000003520 - tpidr_el1 :0x0000000000000000 - tpidr_el0 :0x0000000000000000 - tpidrro_el0 :0x0000000000000000 - dacr32_el2 :0x0000000000000000 - ifsr32_el2 :0x0000000000000000 - par_el1 :0x0000000000000000 - far_el1 :0x0000000000000000 - afsr0_el1 :0x0000000000000000 - afsr1_el1 :0x0000000000000000 - contextidr_el1 :0x0000000000000000 - vbar_el1 :0x0000000004027000 - cntp_ctl_el0 :0x0000000000000000 - cntp_cval_el0 :0x0000000000000000 - cntv_ctl_el0 :0x0000000000000000 - cntv_cval_el0 :0x0000000000000000 - cntkctl_el1 :0x0000000000000000 - sp_el0 :0x0000000004010780 + x0 = 0x000000002a4a0000 + x1 = 0x0000000000000001 + x2 = 0x0000000000000002 + x3 = 0x0000000000000003 + x4 = 0x0000000000000004 + x5 = 0x0000000000000005 + x6 = 0x0000000000000006 + x7 = 0x0000000000000007 + x8 = 0x0000000000000008 + x9 = 0x0000000000000009 + x10 = 0x0000000000000010 + x11 = 0x0000000000000011 + x12 = 0x0000000000000012 + x13 = 0x0000000000000013 + x14 = 0x0000000000000014 + x15 = 0x0000000000000015 + x16 = 0x0000000000000016 + x17 = 0x0000000000000017 + x18 = 0x0000000000000018 + x19 = 0x0000000000000019 + x20 = 0x0000000000000020 + x21 = 0x0000000000000021 + x22 = 0x0000000000000022 + x23 = 0x0000000000000023 + x24 = 0x0000000000000024 + x25 = 0x0000000000000025 + x26 = 0x0000000000000026 + x27 = 0x0000000000000027 + x28 = 0x0000000000000028 + x29 = 0x0000000000000029 + x30 = 0x0000000088000b78 + scr_el3 = 0x000000000003073d + sctlr_el3 = 0x00000000b0cd183f + cptr_el3 = 0x0000000000000000 + tcr_el3 = 0x000000008080351c + daif = 0x00000000000002c0 + mair_el3 = 0x00000000004404ff + spsr_el3 = 0x0000000060000349 + elr_el3 = 0x0000000088000114 + ttbr0_el3 = 0x0000000004018201 + esr_el3 = 0x00000000be000000 + far_el3 = 0x0000000000000000 + spsr_el1 = 0x0000000000000000 + elr_el1 = 0x0000000000000000 + spsr_abt = 0x0000000000000000 + spsr_und = 0x0000000000000000 + spsr_irq = 0x0000000000000000 + spsr_fiq = 0x0000000000000000 + sctlr_el1 = 0x0000000030d00800 + actlr_el1 = 0x0000000000000000 + cpacr_el1 = 0x0000000000000000 + csselr_el1 = 0x0000000000000000 + sp_el1 = 0x0000000000000000 + esr_el1 = 0x0000000000000000 + ttbr0_el1 = 0x0000000000000000 + ttbr1_el1 = 0x0000000000000000 + mair_el1 = 0x0000000000000000 + amair_el1 = 0x0000000000000000 + tcr_el1 = 0x0000000000000000 + tpidr_el1 = 0x0000000000000000 + tpidr_el0 = 0x0000000000000000 + tpidrro_el0 = 0x0000000000000000 + par_el1 = 0x0000000000000000 + mpidr_el1 = 0x0000000080000000 + afsr0_el1 = 0x0000000000000000 + afsr1_el1 = 0x0000000000000000 + contextidr_el1 = 0x0000000000000000 + vbar_el1 = 0x0000000000000000 + cntp_ctl_el0 = 0x0000000000000000 + cntp_cval_el0 = 0x0000000000000000 + cntv_ctl_el0 = 0x0000000000000000 + cntv_cval_el0 = 0x0000000000000000 + cntkctl_el1 = 0x0000000000000000 + sp_el0 = 0x0000000004014940 + isr_el1 = 0x0000000000000000 + dacr32_el2 = 0x0000000000000000 + ifsr32_el2 = 0x0000000000000000 + icc_hppir0_el1 = 0x00000000000003ff + icc_hppir1_el1 = 0x00000000000003ff + icc_ctlr_el3 = 0x0000000000080400 + gicd_ispendr regs (Offsets 0x200-0x278) + Offset Value + 0x200: 0x0000000000000000 + 0x208: 0x0000000000000000 + 0x210: 0x0000000000000000 + 0x218: 0x0000000000000000 + 0x220: 0x0000000000000000 + 0x228: 0x0000000000000000 + 0x230: 0x0000000000000000 + 0x238: 0x0000000000000000 + 0x240: 0x0000000000000000 + 0x248: 0x0000000000000000 + 0x250: 0x0000000000000000 + 0x258: 0x0000000000000000 + 0x260: 0x0000000000000000 + 0x268: 0x0000000000000000 + 0x270: 0x0000000000000000 + 0x278: 0x0000000000000000 Guidelines for Reset Handlers ----------------------------- @@ -1275,6 +1302,8 @@ In other words, the reset handler should be able to detect whether an action has already been performed and act as appropriate. Possible courses of actions are, e.g. skip the action the second time, or undo/redo it. +.. _configuring-secure-interrupts: + Configuring secure interrupts ----------------------------- @@ -1711,7 +1740,7 @@ CONFIG section in memory layouts shown below contains: ``bl2_mem_params_descs`` contains parameters passed from BL2 to next the BL image during boot. -``fw_configs`` includes soc_fw_config, tos_fw_config and tb_fw_config. +``fw_configs`` includes soc_fw_config, tos_fw_config, tb_fw_config and fw_config. **FVP with TSP in Trusted SRAM with firmware configs :** (These diagrams only cover the AArch64 case) @@ -1736,7 +1765,7 @@ BL image during boot. | | <<<<<<<<<<<<< | BL31 PROGBITS | | | <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL32 | - 0x04002000 +----------+ +----------------+ + 0x04003000 +----------+ +----------------+ | CONFIG | 0x04001000 +----------+ | Shared | @@ -1773,7 +1802,7 @@ BL image during boot. |--------------| <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL31 PROGBITS | | | +----------------+ - +--------------+ + 0x04003000 +--------------+ | CONFIG | 0x04001000 +--------------+ | Shared | @@ -1807,7 +1836,7 @@ BL image during boot. |----------| <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL31 PROGBITS | | | +----------------+ - 0x04002000 +----------+ + 0x04003000 +----------+ | CONFIG | 0x04001000 +----------+ | Shared | @@ -1838,7 +1867,7 @@ BL image during boot. | BL2 | <<<<<<<<<<<<< | | |----------| <<<<<<<<<<<<< |----------------| | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| <<<<<<<<<<<<< |----------------| + | | <<<<<<<<<<<<< |----------------| | | <<<<<<<<<<<<< | BL32 | | | +----------------+ | | @@ -1875,7 +1904,7 @@ BL image during boot. | BL2 | <<<<<<<<<<<<< | | |----------| <<<<<<<<<<<<< |----------------| | SCP_BL2 | <<<<<<<<<<<<< | BL31 PROGBITS | - |----------| +----------------+ + | | +----------------+ 0x04001000 +----------+ | MHU | 0x04000000 +----------+ @@ -2690,20 +2719,20 @@ kernel at boot time. These can be found in the ``fdts`` directory. - `Power State Coordination Interface PDD`_ -- `SMC Calling Convention PDD`_ +- `SMC Calling Convention`_ - :ref:`Interrupt Management Framework` -------------- -*Copyright (c) 2013-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2013-2020, Arm Limited and Contributors. All rights reserved.* .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _SMCCC: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _SMCCC: https://developer.arm.com/docs/den0028/latest .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf .. _Power State Coordination Interface PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0022d/Power_State_Coordination_Interface_PDD_v1_1_DEN0022D.pdf -.. _Arm ARM: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.e/index.html -.. _SMC Calling Convention PDD: http://infocenter.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest +.. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest .. _Trusted Board Boot Requirements CLIENT (TBBR-CLIENT) Armv8-A (ARM DEN0006D): https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a .. |Image 1| image:: ../resources/diagrams/rt-svc-descs-layout.png diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst index d155cb356..dfb2eac8e 100644 --- a/docs/design/interrupt-framework-design.rst +++ b/docs/design/interrupt-framework-design.rst @@ -138,6 +138,8 @@ Non-secure interrupts reason to route the interrupt to EL3 software and then hand it back to non-secure software for handling. +.. _EL3 interrupts: + EL3 interrupts ^^^^^^^^^^^^^^ @@ -148,10 +150,8 @@ EL3 interrupts However, when ``EL3_EXCEPTION_HANDLING`` is ``1``, this routing model is invalid as EL3 interrupts are unconditionally routed to EL3, and EL3 - interrupts will always preempt Secure EL1/EL0 execution. See `exception - handling`__ documentation. - - .. __: exception-handling.rst#interrupt-handling + interrupts will always preempt Secure EL1/EL0 execution. See :ref:`exception + handling<interrupt-handling>` documentation. #. **CSS=0, TEL3=1**. Interrupt is routed to EL3 when execution is in Secure-EL1/Secure-EL0. This is a valid routing model as secure software @@ -301,6 +301,8 @@ This section describes in detail the role of each software component (see `Software components`_) during the registration of a handler for an interrupt type. +.. _el3-runtime-firmware: + EL3 runtime firmware ~~~~~~~~~~~~~~~~~~~~ @@ -899,14 +901,14 @@ it is generated during execution in the TSP with ``PSTATE.I`` = 0 when the |Image 2| -Secure payload -~~~~~~~~~~~~~~ +.. _sp-synchronous-int: + +Secure payload interrupt handling +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The SP should implement one or both of the synchronous and asynchronous interrupt handling models depending upon the interrupt routing model it has -chosen (as described in section `Secure Payload`__). - -.. __: #sp-int-registration +chosen (as described in section :ref:`Secure Payload <sp-int-registration>`). In the synchronous model, it should begin handling a Secure-EL1 interrupt after receiving control from the SPD service at an entrypoint agreed upon during build @@ -1011,9 +1013,9 @@ TSP by returning ``SMC_UNK`` error. -------------- -*Copyright (c) 2014-2019, Arm Limited and Contributors. All rights reserved.* +*Copyright (c) 2014-2020, Arm Limited and Contributors. All rights reserved.* -.. _SMC calling convention: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html +.. _SMC calling convention: https://developer.arm.com/docs/den0028/latest .. |Image 1| image:: ../resources/diagrams/sec-int-handling.png .. |Image 2| image:: ../resources/diagrams/non-sec-int-handling.png diff --git a/docs/design/trusted-board-boot-build.rst b/docs/design/trusted-board-boot-build.rst index 202524316..dd61b61f5 100644 --- a/docs/design/trusted-board-boot-build.rst +++ b/docs/design/trusted-board-boot-build.rst @@ -32,26 +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. Two locations are currently supported (see + 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 both Juno and FVP models, the default value corresponds to an - ECDSA-SECP256R1 public key hash, whose private part is not currently - available. + 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 ROTPK hash that is hardcoded - in the Arm platform port. The private/public RSA key pair may be - found in ``plat/arm/board/common/rotpk``. + - ``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. - - ``ARM_ROTPK_LOCATION=devel_ecdsa``: use the ROTPK hash that is hardcoded - in the Arm platform port. The private/public ECDSA key pair may be - found in ``plat/arm/board/common/rotpk``. + - ``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. Example of command line using RSA development keys: @@ -65,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 @@ -103,12 +104,12 @@ 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. -------------- -*Copyright (c) 2019, Arm Limited. All rights reserved.* +*Copyright (c) 2019-2020, Arm Limited. All rights reserved.* .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git .. _mbed TLS Security Center: https://tls.mbed.org/security diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst index 49e8adb98..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 @@ -229,9 +230,37 @@ library that is required is given in the :ref:`Prerequisites` document. Instructions for building and using the tool can be found at :ref:`tools_build_cert_create`. +Authenticated Encryption Framework +---------------------------------- + +The authenticated encryption framework included in TF-A provides support to +implement the optional firmware encryption feature. This feature can be +optionally enabled on platforms to implement the optional requirement: +R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_ +document. + +Note that due to security considerations and complexity of this feature, it is +marked as experimental. + +Firmware Encryption Tool +------------------------ + +The ``encrypt_fw`` tool is built and runs on the host machine as part of the +TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain +firmware image as input and generates the encrypted firmware image which can +then be passed as input to the ``fiptool`` utility for creating the FIP. + +The encrypted firmwares are also stored individually in the output build +directory. + +The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL +library version 1.0.1 or later to do authenticated encryption operation. +Instructions for building and using the tool can be found in the +:ref:`tools_build_enctool`. + -------------- -*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 |