diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst new file mode 100644 index 0000000..3b14446 --- /dev/null +++ b/docs/frequently-asked-questions.rst @@ -0,0 +1,88 @@ +How do I update a Pull Request? +------------------------------- + +Often it is necessary to update a Pull Request (PR) before it is merged. When +you push to the source topic branch of an open PR, the PR is automatically +updated with the new commits. + +If you need to modify existing commits in the PR (for example following review +comments), then use the ``--force`` option when pushing. Any comments that apply +to previous versions of the PR are retained in the PR. Sometimes it may be +confusing whether comments apply to the current or a previous version of the PR, +especially if there are several rounds of rework. In this case, you may be asked +to close the PR and create a new one with the latest commits. The new PR should +have a version appended to the name (e.g. "My topic v2") and you should create a +link to the old PR so that reviewers can easily find previous versions. + +When the PR is finally merged, you will be given the option of deleting your +topic branch. It is recommended you delete this (and any previous topic branch +versions) to avoid polluting your fork with obsolete branches. + +How long will my Pull Request take to merge? +-------------------------------------------- + +This can vary a lot, depending on: + +* How important the Pull Request (PR) is considered by the TF maintainers. Where + possible, you should indicate the required timescales for merging the PR and + the impact of any delay. + +* The quality of the PR. PRs are likely to be merged quicker if they follow the + coding guidelines, have already had some code review, and have been + appropriately tested. Note that PRs from Arm engineers go through an internal + review process before appearing on GitHub, therefore may appear to be merged + more quickly. + +* The impact of the PR. For example, a PR that changes a key generic API is + likely to receive much greater scrutiny than a local change to a specific + platform port. + +* How much opportunity for external review is required. For example, the TF + maintainers may not wait for external review comments to merge trivial + bug-fixes but may wait up to a week to merge major changes, or ones requiring + feedback from specific parties. + +* How many other topics need to be integrated and the risk of conflict between + the topics. + +* Is there a code freeze in place in preparation for the release. Please refer + the `release information`_ for more details. + +* The workload of the TF maintainers. + +Feel free to add a comment to your PR to get an estimate of when it will +be merged. + +How long will it take for my merged Pull Request to go from ``integration`` to ``master``? +------------------------------------------------------------------------------------------ + +This depends on how many concurrent Pull Requests (PRs) are being processed at +the same time. In simple cases where all potential regressions have already been +tested, the delay will be less than 1 day. If the TF maintainers are trying to +merge several things over the course of a few days, it might take up to a week. +Typically, it will be 1-2 days. + +The worst case is if the TF maintainers are trying to make a release while also +receiving PRs that will not be merged into the release. In this case, the PRs +will be merged onto ``integration``, which will temporarily diverge from the +release branch. The ``integration`` branch will be rebased onto ``master`` after +the release, and then ``master`` will be fast-forwarded to ``integration`` 1-2 +days later. This whole process could take up 4 weeks. Please refer the `release +information`_ for code freeze dates. The TF maintainers will inform the PR owner +if this is going to happen. + +It is OK to create a PR based on commits that are only available in +``integration`` or another PR, rather than ``master``. There is a risk that the +dependency commits will change (for example due to PR rework or integration +problems). If this happens, the dependent PR will need reworking. + +What are these strange comments in my Pull Request? +--------------------------------------------------- + +For example, comments like "Can one of the admins verify this patch?" or "test +this please". These are associated with Arm's Continuous Integration +infrastructure and can be safely ignored. Those who are curious can see the +documentation for `this Jenkins plugin`_ for more details. + +.. _release information: release-information +.. _this Jenkins plugin: https://wiki.jenkins-ci.org/display/JENKINS/GitHub+pull+request+builder+plugin diff --git a/docs/image-terminology.rst b/docs/image-terminology.rst new file mode 100644 index 0000000..1c64297 --- /dev/null +++ b/docs/image-terminology.rst @@ -0,0 +1,171 @@ +Trusted Firmware images +----------------------- + +This page contains the current name, abbreviated name and purpose of the various +images referred to in the Trusted Firmware project. + +Some general notes: + +- Some of the names and abbreviated names have changed to accomodate new + requirements. The changed names are as backward compatible as possible to + minimize confusion. Where applicable, the previous names are indicated. Some + code, documentation and build artefacts may still refer to the previous names; + these will inevitably take time to catch up. + +- The main name change is to prefix each image with the processor it corresponds + to (for example ``AP_``, ``SCP_``, ...). In situations where there is no + ambiguity (for example, within AP specific code/documentation), it is + permitted to omit the processor prefix (for example, just BL1 instead of + ``AP_BL1``). + +- Previously, the format for 3rd level images had 2 forms; ``BL3`` was either + suffixed with a dash ("-") followed by a number (for example, ``BL3-1``) or a + subscript number, depending on whether rich text formatting was available. + This was confusing and often the dash gets omitted in practice. Therefore the + new form is to just omit the dash and not use subscript formatting. + +- The names no longer contain dash ("-") characters at all. In some places (for + example, function names) it's not possible to use this character. All dashes + are either removed or replaced by underscores ("_"). + +- The abbreviation BL stands for BootLoader. This is a historical anomaly. + Clearly, many of these images are not BootLoaders, they are simply firmware + images. However, the BL abbreviation is now widely used and is retained for + backwards compatibility. + +- The image names are not case sensitive. For example, ``bl1`` is + interchangeable with ``BL1``, although mixed case should be avoided. + +AP Boot ROM: ``AP_BL1`` +~~~~~~~~~~~~~~~~~~~~~~~ + +Typically, this is the first code to execute on the AP and cannot be modified. +Its primary purpose is to perform the minimum intialization necessary to load +and authenticate an updateable AP firmware image into an executable RAM +location, then hand-off control to that image. + +AP RAM Firmware: ``AP_BL2`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the 2nd stage AP firmware. It is currently also known as the "Trusted +Boot Firmware". Its primary purpose is to perform any additional initialization +required to load and authenticate all 3rd level firmware images into their +executable RAM locations, then hand-off control to the EL3 Runtime Firmware. + +EL3 Runtime Firmware: ``AP_BL31`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Also known as "SoC AP firmware" or "EL3 monitor firmware". Its primary purpose +is to handle transitions between the normal and secure world. + +Secure-EL1 Payload (SP): ``AP_BL32`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Typically this is a TEE or Trusted OS, providing runtime secure services to the +normal world. However, it may refer to a more abstract Secure-EL1 Payload (SP). +Note that this abbreviation should only be used in systems where there is a +single or primary image executing at Secure-EL1. In systems where there are +potentially multiple SPs and there is no concept of a primary SP, this +abbreviation should be avoided; use the recommended **Other AP 3rd level +images** abbreviation instead. + +AP Normal World Firmware: ``AP_BL33`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For example, UEFI or uboot. Its primary purpose is to boot a normal world OS. + +Other AP 3rd level images: ``AP_BL3_XXX`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The abbreviated names of the existing 3rd level images imply a load/execution +ordering (for example, ``AP_BL31 -> AP_BL32 -> AP_BL33``). Some systems may +have additional images and/or a different load/execution ordering. The +abbreviated names of the existing images are retained for backward compatibility +but new 3rd level images should be suffixed with an underscore followed by text +identifier, not a number. + +In systems where 3rd level images are provided by different vendors, the +abbreviated name should identify the vendor as well as the image +function. For example, ``AP_BL3_ARM_RAS``. + +SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Typically, this is the first code to execute on the SCP and cannot be modified. +Its primary purpose is to perform the minimum intialization necessary to load +and authenticate an updateable SCP firmware image into an executable RAM +location, then hand-off control to that image. This may be performed in +conjunction with other processor firmware (for example, ``AP_BL1`` and +``AP_BL2``). + +This image was previously abbreviated as ``BL0`` but in some systems, the SCP +may directly load/authenticate its own firmware. In these systems, it doesn't +make sense to interleave the image terminology for AP and SCP; both AP and SCP +Boot ROMs are ``BL1`` from their own point of view. + +SCP RAM Firmware: ``SCP_BL2`` (previously ``BL3-0``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the 2nd stage SCP firmware. It is currently also known as the "SCP +runtime firmware" but it could potentially be an intermediate firmware if the +SCP needs to load/authenticate multiple 3rd level images in future. + +This image was previously abbreviated as BL3-0 but from the SCP's point of view, +this has always been the 2nd stage firmware. The previous name is too +AP-centric. + +Firmware update images +---------------------- + +The terminology for these images has not been widely adopted yet but they have +to be considered in a production Trusted Board Boot solution. + +AP Firmware Update Boot ROM: ``AP_NS_BL1U`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Typically, this is the first normal world code to execute on the AP during a +firmware update operation, and cannot be modified. Its primary purpose is to +load subequent firmware update images from an external interface and communicate +with ``AP_BL1`` to authenticate those images. + +During firmware update, there are (potentially) multiple transitions between the +secure and normal world. The "level" of the BL image is relative to the world +it's in so it makes sense to encode "NS" in the normal world images. The absence +of "NS" implies a secure world image. + +AP Firmware Update Config: ``AP_BL2U`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This image does the minimum necessary AP secure world configuration required to +complete the firmware update operation. It is potentially a subset of ``AP_BL2`` +functionality. + +SCP Firmware Update Config: ``SCP_BL2U`` (previously ``BL2-U0``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This image does the minimum necessary SCP secure world configuration required to +complete the firmware update operation. It is potentially a subset of +``SCP_BL2`` functionality. + +AP Firmware Updater: ``AP_NS_BL2U`` (previously ``BL3-U``) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the 2nd stage AP normal world firmware updater. Its primary purpose is +to load a new set of firmware images from an external interface and write them +into non-volatile storage. + +Other processor firmware images +------------------------------- + +Some systems may have additional processors to the AP and SCP. For example, a +Management Control Processor (MCP). Images for these processors should follow +the same terminology, with the processor abbreviation prefix, followed by +underscore and the level of the firmware image. + +For example, + +MCP Boot ROM: ``MCP_BL1`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +MCP RAM Firmware: ``MCP_BL2`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/psci-performance-juno.rst b/docs/psci-performance-juno.rst new file mode 100644 index 0000000..a28f732 --- /dev/null +++ b/docs/psci-performance-juno.rst @@ -0,0 +1,285 @@ +This document summarises the findings of performance measurements of key +operations in the ARM Trusted Firmware (TF) Power State Coordination Interface +(PSCI) implementation, using the in-built Performance Measurement Framework +(PMF) and runtime instrumentation timestamps. + +Method +------ + +We used the `Juno R1 platform`_ for these tests, which has 4 x Cortex-A53 and 2 +x Cortex-A57 clusters running at the following frequencies: + ++-----------------+--------------------+ +| Domain | Frequency (MHz) | ++=================+====================+ +| Cortex-A57 | 900 (nominal) | ++-----------------+--------------------+ +| Cortex-A53 | 650 (underdrive) | ++-----------------+--------------------+ +| AXI subsystem | 533 | ++-----------------+--------------------+ + +Juno supports CPU, cluster and system power down states, corresponding to power +levels 0, 1 and 2 respectively. It does not support any retention states. + +We used the upstream `TF master as of 31/01/2017`_, building the platform using +the ``ENABLE_RUNTIME_INSTRUMENTATION`` option: + +:: + + make PLAT=juno ENABLE_RUNTIME_INSTRUMENTATION=1 \ + SCP_BL2= \ + BL33= \ + all fip + +When using the debug build of TF, there was no noticeable difference in the +results. + +The tests are based on an ARM-internal test framework. The release build of this +framework was used because the results in the debug build became skewed; the +console output prevented some of the tests from executing in parallel. + +The tests consist of both parallel and sequential tests, which are broadly +described as follows: + +- **Parallel Tests** This type of test powers on all the non-lead CPUs and + brings them and the lead CPU to a common synchronization point. The lead CPU + then initiates the test on all CPUs in parallel. + +- **Sequential Tests** This type of test powers on each non-lead CPU in + sequence. The lead CPU initiates the test on a non-lead CPU then waits for the + test to complete before proceeding to the next non-lead CPU. The lead CPU then + executes the test on itself. + +In the results below, CPUs 0-3 refer to CPUs in the little cluster (A53) and +CPUs 4-5 refer to CPUs in the big cluster (A57). In all cases CPU 4 is the lead +CPU. + +``PSCI_ENTRY`` refers to the time taken from entering the TF PSCI implementation +to the point the hardware enters the low power state (WFI). Referring to the TF +runtime instrumentation points, this corresponds to: +``(RT_INSTR_ENTER_HW_LOW_PWR - RT_INSTR_ENTER_PSCI)``. + +``PSCI_EXIT`` refers to the time taken from the point the hardware exits the low +power state to exiting the TF PSCI implementation. This corresponds to: +``(RT_INSTR_EXIT_PSCI - RT_INSTR_EXIT_HW_LOW_PWR)``. + +``CFLUSH_OVERHEAD`` refers to the part of ``PSCI_ENTRY`` taken to flush the +caches. This corresponds to: ``(RT_INSTR_EXIT_CFLUSH - RT_INSTR_ENTER_CFLUSH)``. + +Note there is very little variance observed in the values given (~1us), although +the values for each CPU are sometimes interchanged, depending on the order in +which locks are acquired. Also, there is very little variance observed between +executing the tests sequentially in a single boot or rebooting between tests. + +Given that runtime instrumentation using PMF is invasive, there is a small +(unquantified) overhead on the results. PMF uses the generic counter for +timestamps, which runs at 50MHz on Juno. + +Results and Commentary +---------------------- + +``CPU_SUSPEND`` to deepest power level on all CPUs in parallel +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------+---------------------+--------------------+--------------------------+ +| CPU | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) | ++=======+=====================+====================+==========================+ +| 0 | 27 | 20 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 1 | 114 | 86 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 2 | 202 | 58 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 3 | 375 | 29 | 94 | ++-------+---------------------+--------------------+--------------------------+ +| 4 | 20 | 22 | 6 | ++-------+---------------------+--------------------+--------------------------+ +| 5 | 290 | 18 | 206 | ++-------+---------------------+--------------------+--------------------------+ + +A large variance in ``PSCI_ENTRY`` and ``PSCI_EXIT`` times across CPUs is +observed due to TF PSCI lock contention. In the worst case, CPU 3 has to wait +for the 3 other CPUs in the cluster (0-2) to complete ``PSCI_ENTRY`` and release +the lock before proceeding. + +The ``CFLUSH_OVERHEAD`` times for CPUs 3 and 5 are higher because they are the +last CPUs in their respective clusters to power down, therefore both the L1 and +L2 caches are flushed. + +The ``CFLUSH_OVERHEAD`` time for CPU 5 is a lot larger than that for CPU 3 +because the L2 cache size for the big cluster is lot larger (2MB) compared to +the little cluster (1MB). + +``CPU_SUSPEND`` to power level 0 on all CPUs in parallel +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------+---------------------+--------------------+--------------------------+ +| CPU | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) | ++=======+=====================+====================+==========================+ +| 0 | 116 | 14 | 8 | ++-------+---------------------+--------------------+--------------------------+ +| 1 | 204 | 14 | 8 | ++-------+---------------------+--------------------+--------------------------+ +| 2 | 287 | 13 | 8 | ++-------+---------------------+--------------------+--------------------------+ +| 3 | 376 | 13 | 9 | ++-------+---------------------+--------------------+--------------------------+ +| 4 | 29 | 15 | 7 | ++-------+---------------------+--------------------+--------------------------+ +| 5 | 21 | 15 | 8 | ++-------+---------------------+--------------------+--------------------------+ + +There is no lock contention in TF generic code at power level 0 but the large +variance in ``PSCI_ENTRY`` times across CPUs is due to lock contention in Juno +platform code. The platform lock is used to mediate access to a single SCP +communication channel. This is compounded by the SCP firmware waiting for each +AP CPU to enter WFI before making the channel available to other CPUs, which +effectively serializes the SCP power down commands from all CPUs. + +On platforms with a more efficient CPU power down mechanism, it should be +possible to make the ``PSCI_ENTRY`` times smaller and consistent. + +The ``PSCI_EXIT`` times are consistent across all CPUs because TF does not +require locks at power level 0. + +The ``CFLUSH_OVERHEAD`` times for all CPUs are small and consistent since only +the cache associated with power level 0 is flushed (L1). + +``CPU_SUSPEND`` to deepest power level on all CPUs in sequence +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------+---------------------+--------------------+--------------------------+ +| CPU | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) | ++=======+=====================+====================+==========================+ +| 0 | 114 | 20 | 94 | ++-------+---------------------+--------------------+--------------------------+ +| 1 | 114 | 20 | 94 | ++-------+---------------------+--------------------+--------------------------+ +| 2 | 114 | 20 | 94 | ++-------+---------------------+--------------------+--------------------------+ +| 3 | 114 | 20 | 94 | ++-------+---------------------+--------------------+--------------------------+ +| 4 | 195 | 22 | 180 | ++-------+---------------------+--------------------+--------------------------+ +| 5 | 21 | 17 | 6 | ++-------+---------------------+--------------------+--------------------------+ + +The ``CLUSH_OVERHEAD`` times for lead CPU 4 and all CPUs in the non-lead cluster +are large because all other CPUs in the cluster are powered down during the +test. The ``CPU_SUSPEND`` call powers down to the cluster level, requiring a +flush of both L1 and L2 caches. + +The ``CFLUSH_OVERHEAD`` time for CPU 4 is a lot larger than those for the little +CPUs because the L2 cache size for the big cluster is lot larger (2MB) compared +to the little cluster (1MB). + +The ``PSCI_ENTRY`` and ``CFLUSH_OVERHEAD`` times for CPU 5 are low because lead +CPU 4 continues to run while CPU 5 is suspended. Hence CPU 5 only powers down to +level 0, which only requires L1 cache flush. + +``CPU_SUSPEND`` to power level 0 on all CPUs in sequence +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------+---------------------+--------------------+--------------------------+ +| CPU | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) | ++=======+=====================+====================+==========================+ +| 0 | 22 | 14 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 1 | 22 | 14 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 2 | 21 | 14 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 3 | 22 | 14 | 5 | ++-------+---------------------+--------------------+--------------------------+ +| 4 | 17 | 14 | 6 | ++-------+---------------------+--------------------+--------------------------+ +| 5 | 18 | 15 | 6 | ++-------+---------------------+--------------------+--------------------------+ + +Here the times are small and consistent since there is no contention and it is +only necessary to flush the cache to power level 0 (L1). This is the best case +scenario. + +The ``PSCI_ENTRY`` times for CPUs in the big cluster are slightly smaller than +for the CPUs in little cluster due to greater CPU performance. + +The ``PSCI_EXIT`` times are generally lower than in the last test because the +cluster remains powered on throughout the test and there is less code to execute +on power on (for example, no need to enter CCI coherency) + +``CPU_OFF`` on all non-lead CPUs in sequence then ``CPU_SUSPEND`` on lead CPU to deepest power level +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The test sequence here is as follows: + +1. Call ``CPU_ON`` and ``CPU_OFF`` on each non-lead CPU in sequence. + +2. Program wake up timer and suspend the lead CPU to the deepest power level. + +3. Call ``CPU_ON`` on non-lead CPU to get the timestamps from each CPU. + ++-------+---------------------+--------------------+--------------------------+ +| CPU | ``PSCI_ENTRY`` (us) | ``PSCI_EXIT`` (us) | ``CFLUSH_OVERHEAD`` (us) | ++=======+=====================+====================+==========================+ +| 0 | 110 | 28 | 93 | ++-------+---------------------+--------------------+--------------------------+ +| 1 | 110 | 28 | 93 | ++-------+---------------------+--------------------+--------------------------+ +| 2 | 110 | 28 | 93 | ++-------+---------------------+--------------------+--------------------------+ +| 3 | 111 | 28 | 93 | ++-------+---------------------+--------------------+--------------------------+ +| 4 | 195 | 22 | 181 | ++-------+---------------------+--------------------+--------------------------+ +| 5 | 20 | 23 | 6 | ++-------+---------------------+--------------------+--------------------------+ + +The ``CFLUSH_OVERHEAD`` times for all little CPUs are large because all other +CPUs in that cluster are powerered down during the test. The ``CPU_OFF`` call +powers down to the cluster level, requiring a flush of both L1 and L2 caches. + +The ``PSCI_ENTRY`` and ``CFLUSH_OVERHEAD`` times for CPU 5 are small because +lead CPU 4 is running and CPU 5 only powers down to level 0, which only requires +an L1 cache flush. + +The ``CFLUSH_OVERHEAD`` time for CPU 4 is a lot larger than those for the little +CPUs because the L2 cache size for the big cluster is lot larger (2MB) compared +to the little cluster (1MB). + +The ``PSCI_EXIT`` times for CPUs in the big cluster are slightly smaller than +for CPUs in the little cluster due to greater CPU performance. These times +generally are greater than the ``PSCI_EXIT`` times in the ``CPU_SUSPEND`` tests +because there is more code to execute in the "on finisher" compared to the +"suspend finisher" (for example, GIC redistributor register programming). + +``PSCI_VERSION`` on all CPUs in parallel +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Since very little code is associated with ``PSCI_VERSION``, this test +approximates the round trip latency for handling a fast SMC at EL3 in TF. + ++-------+-------------------+ +| CPU | TOTAL TIME (ns) | ++=======+===================+ +| 0 | 3020 | ++-------+-------------------+ +| 1 | 2940 | ++-------+-------------------+ +| 2 | 2980 | ++-------+-------------------+ +| 3 | 3060 | ++-------+-------------------+ +| 4 | 520 | ++-------+-------------------+ +| 5 | 720 | ++-------+-------------------+ + +The times for the big CPUs are less than the little CPUs due to greater CPU +performance. + +We suspect the time for lead CPU 4 is shorter than CPU 5 due to subtle cache +effects, given that these measurements are at the nano-second level. + +.. _Juno R1 platform: https://www.arm.com/files/pdf/Juno_r1_ARM_Dev_datasheet.pdf +.. _TF master as of 31/01/2017: https://github.com/ARM-software/arm-trusted-firmware/tree/c38b36d diff --git a/docs/release-information.rst b/docs/release-information.rst new file mode 100644 index 0000000..af3cbbe --- /dev/null +++ b/docs/release-information.rst @@ -0,0 +1,89 @@ +TF-A Release Information +======================== + +.. section-numbering:: + :suffix: . + +.. contents:: + +-------------- + +Project Release Cadence +----------------------- + +The project currently aims to do a release once every 6 months which will be +tagged on the master branch. There will be a code freeze (stop merging +non-essential PRs) up to 4 weeks prior to the target release date. The release +candidates will start appearing after this and only bug fixes or updates +required for the release will be merged. The maintainers are free to use their +judgement on what PRs are essential for the release. A release branch may be +created after code freeze if there are significant PRs that need merging onto +the integration branch during the merge window. + +The release testing will be performed on release candidates and depending on +issues found, additional release candidates may be created to fix the issues. + +:: + + |<----------6 months---------->| + |<---4 weeks--->| |<---4 weeks--->| + +-----------------------------------------------------------> time + | | | | + code freeze ver w.x code freeze ver y.z + + +Upcoming Releases +~~~~~~~~~~~~~~~~~ + +These are the estimated dates for the upcoming release. These may change +depending on project requirement and partner feedback. + ++-----------------+---------------------------+------------------------------+ +| Release Version | Target Date | Expected Code Freeze | ++=================+===========================+==============================+ +| v2.0 | 1st week of Oct '18 | 1st week of Sep '18 | ++-----------------+---------------------------+------------------------------+ +| v2.1 | 5th week of Mar '19 | 1st week of Mar '19 | ++-----------------+---------------------------+------------------------------+ + +Removal of Deprecated Interfaces +-------------------------------- + +As mentioned in the `Platform compatibility policy`_, this is a live document +cataloging all the deprecated interfaces in TF-A project and the Release version +after which it will be removed. + ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Interface | Deprecation | Removed | Comments | +| | Date | after | | +| | | Release | | ++================================+=============+=========+=========================================================+ +| Legacy Console API | Jan '18 | v2.1 | Deprecated in favour of ``MULTI_CONSOLE_API`` | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Weak default | Oct '18 | v2.1 | The default implementations are defined in | +| ``plat_crash_console_*`` | | | `crash_console_helpers.S`_. The platforms have to | +| APIs | | | define ``plat_crash_console_*``. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| ``finish_console_register`` | Oct '18 | v2.1 | The old version of the macro is deprecated. See commit | +| macro in | | | cc5859c_ for more details. | +| ``MULTI_CONSOLE_API`` | | | | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Types ``tzc_action_t`` and | Oct '18 | v2.1 | Using logical operations such as OR in enumerations | +| ``tzc_region_attributes_t`` | | | goes against the MISRA guidelines. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Macro ``EL_IMPLEMENTED()`` | Oct '18 | v2.1 | Deprecated in favour of ``el_implemented()``. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| ``get_afflvl_shift()``, | Dec '18 | v2.1 | Removed. | +| ``mpidr_mask_lower_afflvls()``,| | | | +| and ``eret()``. | | | | ++--------------------------------+-------------+---------+---------------------------------------------------------+ +| Extra include paths in the | Jan '18 | v2.1 | Now it is needed to use the full path of the common | +| Makefile in ``INCLUDES``. | | | header files. More information in commit 09d40e0e0828_. | ++--------------------------------+-------------+---------+---------------------------------------------------------+ + +*Copyright (c) 2018, Arm Limited and Contributors. All rights reserved.* + +.. _Platform compatibility policy: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/platform-compatibility-policy.rst +.. _crash_console_helpers.S: https://github.com/ARM-software/arm-trusted-firmware/blob/master/plat/common/aarch64/crash_console_helpers.S +.. _cc5859c: https://github.com/ARM-software/arm-trusted-firmware/commit/cc5859ca19ff546c35eb0331000dae090b6eabcf +.. _09d40e0e0828: https://github.com/ARM-software/arm-trusted-firmware/commit/09d40e0e08283a249e7dce0e106c07c5141f9b7e diff --git a/docs/security-center.rst b/docs/security-center.rst new file mode 100644 index 0000000..825b110 --- /dev/null +++ b/docs/security-center.rst @@ -0,0 +1,100 @@ +Security Disclosures +-------------------- + +We disclose all security vulnerabilities we find or are advised about that are +relevant for ARM Trusted Firmware (TF). We encourage responsible disclosure of +vulnerabilities and inform users as best we can about all possible issues. + +We disclose TF vulnerabilities as Security Advisories. These are listed at the +bottom of this page and announced as issues in the `GitHub issue tracker`_ with +the "security-advisory" tag. You can receive notification emails for these by +watching that project. + +Found a Security Issue? +----------------------- + +Although we try to keep TF secure, we can only do so with the help of the +community of developers and security researchers. + +If you think you have found a security vulnerability, please *do not* report it +in the `GitHub issue tracker`_. Instead send an email to +trusted-firmware-security@arm.com + +Please include: + +* Trusted Firmware version (or commit) affected + +* A description of the concern or vulnerability + +* Details on how to replicate the vulnerability, including: + + - Configuration details + + - Proof of concept exploit code + + - Any additional software or tools required + +We recommend using `this PGP/GPG key`_ for encrypting the information. This key +is also available at http://keyserver.pgp.com and LDAP port 389 of the same +server. The fingerprint for this key is: + +:: + + 1309 2C19 22B4 8E87 F17B FE5C 3AB7 EFCB 45A0 DFD0 + +If you would like replies to be encrypted, please provide your public key. + +Please give us the time to respond to you and fix the vulnerability before going +public. We do our best to respond and fix any issues quickly. We also need to +ensure providers of products that use TF have a chance to consider the +implications of the vulnerability and its remedy. + +Afterwards, we encourage you to write-up your findings about the TF source code. + +Attribution +----------- + +We will name and thank you in the ``change-log.rst`` distributed with the source +code and in any published security advisory. + +Security Advisories +------------------- + ++-----------+------------------------------------------------------------------+ +| ID | Title | ++===========+==================================================================+ +| `TFV-1`_ | Malformed Firmware Update SMC can result in copy of unexpectedly | +| | large data into secure memory | ++-----------+------------------------------------------------------------------+ +| `TFV-2`_ | Enabled secure self-hosted invasive debug interface can allow | +| | normal world to panic secure world | ++-----------+------------------------------------------------------------------+ +| `TFV-3`_ | RO memory is always executable at AArch64 Secure EL1 | ++-----------+------------------------------------------------------------------+ +| `TFV-4`_ | Malformed Firmware Update SMC can result in copy or | +| | authentication of unexpected data in secure memory in AArch32 | +| | state | ++-----------+------------------------------------------------------------------+ +| `TFV-5`_ | Not initializing or saving/restoring PMCR_EL0 can leak secure | +| | world timing information | ++-----------+------------------------------------------------------------------+ +| `TFV-6`_ | Arm Trusted Firmware exposure to speculative processor | +| | vulnerabilities using cache timing side-channels | ++-----------+------------------------------------------------------------------+ +| `TFV-7`_ | Trusted Firmware-A exposure to cache speculation vulnerability | +| | Variant 4 | ++-----------+------------------------------------------------------------------+ +| `TFV-8`_ | Not saving x0 to x3 registers can leak information from one | +| | Normal World SMC client to another | ++-----------+------------------------------------------------------------------+ + +.. _GitHub issue tracker: https://github.com/ARM-software/tf-issues/issues +.. _this PGP/GPG key: Trusted-Firmware-Security.asc +.. _TFV-1: ARM-Trusted-Firmware-Security-Advisory-TFV-1 +.. _TFV-2: ARM-Trusted-Firmware-Security-Advisory-TFV-2 +.. _TFV-3: ARM-Trusted-Firmware-Security-Advisory-TFV-3 +.. _TFV-4: ARM-Trusted-Firmware-Security-Advisory-TFV-4 +.. _TFV-5: ARM-Trusted-Firmware-Security-Advisory-TFV-5 +.. _TFV-6: Arm-Trusted-Firmware-Security-Advisory-TFV-6 +.. _TFV-7: Trusted-Firmware-A-Security-Advisory-TFV-7 +.. _TFV-8: Trusted-Firmware-A-Security-Advisory-TFV-8 diff --git a/docs/security-reporting.asc b/docs/security-reporting.asc new file mode 100644 index 0000000..8c41f7b --- /dev/null +++ b/docs/security-reporting.asc @@ -0,0 +1,45 @@ +-----BEGIN PGP PUBLIC KEY BLOCK----- +Version: PGP Desktop 10.2.0 (Build 2317) + +mQENBFey/QMBCACyxJaLsMYU794ZfzLdY172tHXRJfP0X3b34HU35G7kYl1zNiYc +/NoygtQdtDv/aW1B2A/YTNhGge+gX4BWAREd5CYDbdPEoMWC395/qbnmMmez7YNY +PEJ9Iq9e5AayAWwZTL1zgKwdvE+WTwWok/nMbsifJSEdhdrOIHNqRcZgplUUyZ2R +sDqFtSbACO3xj4Psk8KJ23Ax7UZgULouZOJaHOnyq8F9V/U7zWvX4Odf96XaC1Em +cUTsG0kQfa7Y4Hqqjzowq366I4k2o2LAtuLPWNCvq5jjEceLs2+qV4cNLgyL2dzO +wtUL6EdkrGfkxsPHpsVKXig4wjeX9ehCSqRlABEBAAG0PVRydXN0ZWQgRmlybXdh +cmUgU2VjdXJpdHkgPHRydXN0ZWQtZmlybXdhcmUtc2VjdXJpdHlAYXJtLmNvbT6J +AYwEEAECAHYFAley/SEwFIAAAAAAIAAHcHJlZmVycmVkLWVtYWlsLWVuY29kaW5n +QHBncC5jb21wZ3BtaW1lCAsJCAcDAgEKAhkBGRhsZGFwOi8va2V5c2VydmVyLnBn +cC5jb20FGwMAAAAFFgADAgEFHgEAAAAGFQgJCgMCAAoJEDq378tFoN/QFJsH/0ly +H91LYYzKIQrbolQw7Rp47lgzH88uN1rInYpW2GaTbjwPffAhYJ4VsN8RaiFskD9m +DjMg4vY8p0jPTCUX1Acq20Wq0Ybv3HcrtjUp4ie0+rLUi3043yJyKFMWkJC2Kr+p +SobnxSrAie4HDFUgSaPoh9Qf1zXEzOavdgcziMiyS5iVUf6NXYZ9z82OTZ6TdPKS +u+L5zOHTdrV3+hD54w00Xa+EIE7u4v0to6Uwm977508hyGuvpOVq+u7+S3qJQvnY ++JheStbgLsm6CyoRjyrlTE01ujAD6hI6Ef9yMgEljOBEy4phKAJ67SCRLEOiCp5U +YHFCULwhzIyg2y3WmZSJASIEEAECAAwFAlezAnwFAwASdQAACgkQlxC4m8pXrXzd +GAf/T8YEICI9qQt2vnCtCbBvVaTc2sAphVZ51kZVDqCDPB7znDtJYRBpi/9IPELt +mYwIElMx2mqmahVaeUghmbzmcLZe8QHUi8GanO1mh+ook6uyjRojSIq6VUVV5uUf +tuscfhpilOvUclqMqYEIgXfl08YwS40Kmmj0qokwad0co0zGQ8GEhlgMi2yvJfiG +fPS0Xcn1J0980E/VgJQCAKwZvukrbb32WVwuhgepqs/4/62PZNxglcErioFt6P0A +ik4t9Hr0uErqCeEKiYtmEw5e9ioRdX7CV+tJgIk907Tpv6E0iDFRJHmJBvmsz82O +stOazS3wZ5Xck7asTqkvoyo9Z7kBDQRXsv0DAQgAsmL1UUIWyoNmYJWixSPDmclP +0ul3T1FCOsIlWTeVeshnHByYdgZOfce78ETCUoq8G7qvYm4GRrEDpqVbxqTxJioP +4Li05WDdNCKzSoqWd8ADA48gYnnJEu2NhA7ZkEC6u3+Mdbmd3M0J6nsAWeE0BV1p +F5zI600sJuoH2QNWB7Kv5N3GCFE4IgCIH8MwDo4Y4FTZtygx4GjEtSExiOIz+bpX +2+GkFCQGpIyLHLP4FmQmrsNzsIdEyFuG0IdoVuQ2PtNLiw+Wkm7CXWgRmFx/dtPN +eVnOFWdbTtjBWVv/Z6zbANos2knfc75KR4FCQ6pWRvVeJuMuMopUDkfFDMtR8QAR +AQABiQJBBBgBAgErBQJXsv0EBRsMAAAAwF0gBBkBCAAGBQJXsv0DAAoJENaB8ph8 +s9hu/nsH/Rx696ZR+1vZi5qCTUwo6s0Qa15x4OuyJEM85VgMLVY7/MZpp1Y8If6u +A5BynQpy4QIPxIRsRx6twduW9/gb8UVhpMRPyuJ+5sSv0/KeUqkPbKSUGro2zGlR +sjqPrchi6uafWZqOR/y/DNkEvkgZZaP+f9xs2qWKuoF08yTioo76QoroA4DVuVAT +MkDFe9d3natAmfmjO4kvxuthg3y7R+sdXrCHpYYJZdbiR6gyj7e8whlSLwHQT3lz +7QBL/CvVvL/dmhu5pk8fsksbehepMQTkCJ6GGEamOPEhwh7IvlzhEt97U4uzjuMd +BPjqOCes+4QTmn/+lMTySG0kXxnHOEUACgkQOrfvy0Wg39D8Jgf/Uf3epkMOJ9xm +N1l5vW8tQQ6RR055YQxQ9P6JMyCQGEJmGOcvrasCho69wMQDy4AYVtJaZd25LH/3 +LX/lcyDOP4C9VYXM+IxlcaRmjBKqWx9UzQeeioIkfmjMpJFU846ZP1dacge0lPx8 +p6ocPbM0rkv0xuF/dwkDQd4BPSmv4/3/UM8FRoYo8Q7SHkDR98wJ8FCm6k9wRtWC +K/jzmBswY2TewAHom3jLzTM0FZ/n5Sini3EGAI2EvnQrxWRpeE7ZOkHKqLHEOaHl +zeST4U/cUgxhwgnhbGJ7zmrFsHpYnnZYM3mIKfQ3/EhksZ68TF9IB1tfUiQTij4r +9jWa0ybRdQ== +=nZZb +-----END PGP PUBLIC KEY BLOCK----- diff --git a/docs/security_advisories/security-advisory-tfv-1.rst b/docs/security_advisories/security-advisory-tfv-1.rst new file mode 100644 index 0000000..23b1c98 --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-1.rst @@ -0,0 +1,158 @@ ++----------------+-------------------------------------------------------------+ +| Title | Malformed Firmware Update SMC can result in copy of | +| | unexpectedly large data into secure memory | ++================+=============================================================+ +| CVE ID | CVE-2016-10319 | ++----------------+-------------------------------------------------------------+ +| Date | 18 Oct 2016 | ++----------------+-------------------------------------------------------------+ +| Versions | v1.2 and v1.3 (since commit `48bfb88`_) | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | Platforms that use AArch64 BL1 plus untrusted normal world | +| Affected | firmware update code executing before BL31 | ++----------------+-------------------------------------------------------------+ +| Impact | Copy of unexpectedly large data into the free secure memory | +| | reported by BL1 platform code | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #783`_ | ++----------------+-------------------------------------------------------------+ +| Credit | IOActive | ++----------------+-------------------------------------------------------------+ + +Generic Trusted Firmware (TF) BL1 code contains an SMC interface that is briefly +available after cold reset to support the Firmware Update (FWU) feature (also +known as recovery mode). This allows most FWU functionality to be implemented in +the normal world, while retaining the essential image authentication +functionality in BL1. When cold boot reaches the EL3 Runtime Software (for +example, BL31 on AArch64 systems), the FWU SMC interface is replaced by the EL3 +Runtime SMC interface. Platforms may choose how much of this FWU functionality +to use, if any. + +The BL1 FWU SMC handling code, currently only supported on AArch64, contains +several vulnerabilities that may be exploited when *all* the following +conditions apply: + +1. Platform code uses TF BL1 with the ``TRUSTED_BOARD_BOOT`` build option + enabled. + +2. Platform code arranges for untrusted normal world FWU code to be executed in + the cold boot path, before BL31 starts. Untrusted in this sense means code + that is not in ROM or has not been authenticated or has otherwise been + executed by an attacker. + +3. Platform code copies the insecure pattern described below from the ARM + platform version of ``bl1_plat_mem_check()``. + +The vulnerabilities consist of potential integer overflows in the input +validation checks while handling the ``FWU_SMC_IMAGE_COPY`` SMC. The SMC +implementation is designed to copy an image into secure memory for subsequent +authentication, but the vulnerabilities may allow an attacker to copy +unexpectedly large data into secure memory. Note that a separate vulnerability +is required to leverage these vulnerabilities; for example a way to get the +system to change its behaviour based on the unexpected secure memory contents. + +Two of the vulnerabilities are in the function ``bl1_fwu_image_copy()`` in +``bl1/bl1_fwu.c``. These are listed below, referring to the v1.3 tagged version +of the code: + +- Line 155: + + .. code:: c + + /* + * If last block is more than expected then + * clip the block to the required image size. + */ + if (image_desc->copied_size + block_size > + image_desc->image_info.image_size) { + block_size = image_desc->image_info.image_size - + image_desc->copied_size; + WARN("BL1-FWU: Copy argument block_size > remaining image size." + " Clipping block_size\n"); + } + + /* Make sure the image src/size is mapped. */ + if (bl1_plat_mem_check(image_src, block_size, flags)) { + WARN("BL1-FWU: Copy arguments source/size not mapped\n"); + return -ENOMEM; + } + + INFO("BL1-FWU: Continuing image copy in blocks\n"); + + /* Copy image for given block size. */ + base_addr += image_desc->copied_size; + image_desc->copied_size += block_size; + memcpy((void *)base_addr, (const void *)image_src, block_size); + ... + + This code fragment is executed when the image copy operation is performed in + blocks over multiple SMCs. ``block_size`` is an SMC argument and therefore + potentially controllable by an attacker. A very large value may result in an + integer overflow in the 1st ``if`` statement, which would bypass the check, + allowing an unclipped ``block_size`` to be passed into + ``bl1_plat_mem_check()``. If ``bl1_plat_mem_check()`` also passes, this may + result in an unexpectedly large copy of data into secure memory. + +- Line 206: + + .. code:: c + + /* Make sure the image src/size is mapped. */ + if (bl1_plat_mem_check(image_src, block_size, flags)) { + WARN("BL1-FWU: Copy arguments source/size not mapped\n"); + return -ENOMEM; + } + + /* Find out how much free trusted ram remains after BL1 load */ + mem_layout = bl1_plat_sec_mem_layout(); + if ((image_desc->image_info.image_base < mem_layout->free_base) || + (image_desc->image_info.image_base + image_size > + mem_layout->free_base + mem_layout->free_size)) { + WARN("BL1-FWU: Memory not available to copy\n"); + return -ENOMEM; + } + + /* Update the image size. */ + image_desc->image_info.image_size = image_size; + + /* Copy image for given size. */ + memcpy((void *)base_addr, (const void *)image_src, block_size); + ... + + This code fragment is executed during the 1st invocation of the image copy + operation. Both ``block_size`` and ``image_size`` are SMC arguments. A very + large value of ``image_size`` may result in an integer overflow in the 2nd + ``if`` statement, which would bypass the check, allowing execution to proceed. + If ``bl1_plat_mem_check()`` also passes, this may result in an unexpectedly + large copy of data into secure memory. + +If the platform's implementation of ``bl1_plat_mem_check()`` is correct then it +may help prevent the above 2 vulnerabilities from being exploited. However, the +ARM platform version of this function contains a similar vulnerability: + +- Line 88 of ``plat/arm/common/arm_bl1_fwu.c`` in function of + ``bl1_plat_mem_check()``: + + .. code:: c + + while (mmap[index].mem_size) { + if ((mem_base >= mmap[index].mem_base) && + ((mem_base + mem_size) + <= (mmap[index].mem_base + + mmap[index].mem_size))) + return 0; + + index++; + } + ... + + This function checks that the passed memory region is within one of the + regions mapped in by ARM platforms. Here, ``mem_size`` may be the + ``block_size`` passed from ``bl1_fwu_image_copy()``. A very large value of + ``mem_size`` may result in an integer overflow and the function to incorrectly + return success. Platforms that copy this insecure pattern will have the same + vulnerability. + +.. _48bfb88: https://github.com/ARM-software/arm-trusted-firmware/commit/48bfb88 +.. _Pull Request #783: https://github.com/ARM-software/arm-trusted-firmware/pull/783 diff --git a/docs/security_advisories/security-advisory-tfv-2.rst b/docs/security_advisories/security-advisory-tfv-2.rst new file mode 100644 index 0000000..1c3a28f --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-2.rst @@ -0,0 +1,57 @@ ++----------------+-------------------------------------------------------------+ +| Title | Enabled secure self-hosted invasive debug interface can | +| | allow normal world to panic secure world | ++================+=============================================================+ +| CVE ID | CVE-2017-7564 | ++----------------+-------------------------------------------------------------+ +| Date | 02 Feb 2017 | ++----------------+-------------------------------------------------------------+ +| Versions | All versions up to v1.3 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | All | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Impact | Denial of Service (secure world panic) | ++----------------+-------------------------------------------------------------+ +| Fix Version | 15 Feb 2017 `Pull Request #841`_ | ++----------------+-------------------------------------------------------------+ +| Credit | ARM | ++----------------+-------------------------------------------------------------+ + +The ``MDCR_EL3.SDD`` bit controls AArch64 secure self-hosted invasive debug +enablement. By default, the BL1 and BL31 images of the current version of ARM +Trusted Firmware (TF) unconditionally assign this bit to ``0`` in the early +entrypoint code, which enables debug exceptions from the secure world. This can +be seen in the implementation of the ``el3_arch_init_common`` `AArch64 macro`_ . +Given that TF does not currently contain support for this feature (for example, +by saving and restoring the appropriate debug registers), this may allow a +normal world attacker to induce a panic in the secure world. + +The ``MDCR_EL3.SDD`` bit should be assigned to ``1`` to disable debug exceptions +from the secure world. + +Earlier versions of TF (prior to `commit 495f3d3`_) did not assign this bit. +Since the bit has an architecturally ``UNKNOWN`` reset value, earlier versions +may or may not have the same problem, depending on the platform. + +A similar issue applies to the ``MDCR_EL3.SPD32`` bits, which control AArch32 +secure self-hosted invasive debug enablement. TF assigns these bits to ``00`` +meaning that debug exceptions from Secure EL1 are enabled by the authentication +interface. Therefore this issue only exists for AArch32 Secure EL1 code when +secure privileged invasive debug is enabled by the authentication interface, at +which point the device is vulnerable to other, more serious attacks anyway. + +However, given that TF contains no support for handling debug exceptions, the +``MDCR_EL3.SPD32`` bits should be assigned to ``10`` to disable debug exceptions +from AArch32 Secure EL1. + +Finally, this also issue applies to AArch32 platforms that use the TF SP_MIN +image or integrate the `AArch32 equivalent`_ of the ``el3_arch_init_common`` +macro. Here the affected bits are ``SDCR.SPD``, which should also be assigned to +``10`` instead of ``00`` + +.. _commit 495f3d3: https://github.com/ARM-software/arm-trusted-firmware/commit/495f3d3 +.. _AArch64 macro: https://github.com/ARM-software/arm-trusted-firmware/blob/bcc2bf0/include/common/aarch64/el3_common_macros.S#L85 +.. _AArch32 equivalent: https://github.com/ARM-software/arm-trusted-firmware/blob/bcc2bf0/include/common/aarch32/el3_common_macros.S#L41 +.. _Pull Request #841: https://github.com/ARM-software/arm-trusted-firmware/pull/841 diff --git a/docs/security_advisories/security-advisory-tfv-3.rst b/docs/security_advisories/security-advisory-tfv-3.rst new file mode 100644 index 0000000..4241573 --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-3.rst @@ -0,0 +1,82 @@ ++----------------+-------------------------------------------------------------+ +| Title | RO memory is always executable at AArch64 Secure EL1 | ++================+=============================================================+ +| CVE ID | CVE-2017-7563 | ++----------------+-------------------------------------------------------------+ +| Date | 06 Apr 2017 | ++----------------+-------------------------------------------------------------+ +| Versions | v1.3 (since `Pull Request #662`_) | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | AArch64 BL2, TSP or other users of xlat_tables library | +| Affected | executing at AArch64 Secure EL1 | ++----------------+-------------------------------------------------------------+ +| Impact | Unexpected Privilege Escalation | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #924`_ | ++----------------+-------------------------------------------------------------+ +| Credit | ARM | ++----------------+-------------------------------------------------------------+ + +The translation table library in ARM Trusted Firmware (TF) (under +``lib/xlat_tables`` and ``lib/xlat_tables_v2``) provides APIs to help program +translation tables in the MMU. The xlat\_tables client specifies its required +memory mappings in the form of ``mmap_region`` structures. Each ``mmap_region`` +has memory attributes represented by the ``mmap_attr_t`` enumeration type. This +contains flags to control data access permissions (``MT_RO``/``MT_RW``) and +instruction execution permissions (``MT_EXECUTE``/``MT_EXECUTE_NEVER``). Thus a +mapping specifying both ``MT_RO`` and ``MT_EXECUTE_NEVER`` should result in a +Read-Only (RO), non-executable memory region. + +This feature does not work correctly for AArch64 images executing at Secure EL1. +Any memory region mapped as RO will always be executable, regardless of whether +the client specified ``MT_EXECUTE`` or ``MT_EXECUTE_NEVER``. + +The vulnerability is known to affect the BL2 and Test Secure Payload (TSP) +images on platforms that enable the ``SEPARATE_CODE_AND_RODATA`` build option, +which includes all ARM standard platforms, and the upstream Xilinx and NVidia +platforms. The RO data section for these images on these platforms is +unexpectedly executable instead of non-executable. Other platforms or +``xlat_tables`` clients may also be affected. + +The vulnerability primarily manifests itself after `Pull Request #662`_. Before +that, ``xlat_tables`` clients could not specify instruction execution +permissions separately to data access permissions. All RO normal memory regions +were implicitly executable. Before `Pull Request #662`_. the vulnerability +would only manifest itself for device memory mapped as RO; use of this mapping +is considered rare, although the upstream QEMU platform uses this mapping when +the ``DEVICE2_BASE`` build option is used. + +Note that one or more separate vulnerabilities are also required to exploit this +vulnerability. + +The vulnerability is due to incorrect handling of the execute-never bits in the +translation tables. The EL3 translation regime uses a single ``XN`` bit to +determine whether a region is executable. The Secure EL1&0 translation regime +handles 2 Virtual Address (VA) ranges and so uses 2 bits, ``UXN`` and ``PXN``. +The ``xlat_tables`` library only handles the ``XN`` bit, which maps to ``UXN`` +in the Secure EL1&0 regime. As a result, this programs the Secure EL0 execution +permissions but always leaves the memory as executable at Secure EL1. + +The vulnerability is mitigated by the following factors: + +- The xlat\_tables library ensures that all Read-Write (RW) memory regions are + non-executable by setting the ``SCTLR_ELx.WXN`` bit. This overrides any value + of the ``XN``, ``UXN`` or ``PXN`` bits in the translation tables. See the + ``enable_mmu()`` function: + + .. code:: c + + sctlr = read_sctlr_el##_el(); \ + sctlr |= SCTLR_WXN_BIT | SCTLR_M_BIT; \ + +- AArch32 configurations are unaffected. Here the ``XN`` bit controls execution + privileges of the currently executing translation regime, which is the desired + behaviour. + +- ARM TF EL3 code (for example BL1 and BL31) ensures that all non-secure memory + mapped into the secure world is non-executable by setting the ``SCR_EL3.SIF`` + bit. See the ``el3_arch_init_common`` macro in ``el3_common_macros.S``. + +.. _Pull Request #662: https://github.com/ARM-software/arm-trusted-firmware/pull/662 +.. _Pull Request #924: https://github.com/ARM-software/arm-trusted-firmware/pull/924 diff --git a/docs/security_advisories/security-advisory-tfv-4.rst b/docs/security_advisories/security-advisory-tfv-4.rst new file mode 100644 index 0000000..9f304c6 --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-4.rst @@ -0,0 +1,120 @@ ++----------------+-------------------------------------------------------------+ +| Title | Malformed Firmware Update SMC can result in copy or | +| | authentication of unexpected data in secure memory in | +| | AArch32 state | ++================+=============================================================+ +| CVE ID | CVE-2017-9607 | ++----------------+-------------------------------------------------------------+ +| Date | 20 Jun 2017 | ++----------------+-------------------------------------------------------------+ +| Versions | None (only between 22 May 2017 and 14 June 2017) | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | Platforms that use AArch32 BL1 plus untrusted normal world | +| Affected | firmware update code executing before BL31 | ++----------------+-------------------------------------------------------------+ +| Impact | Copy or authentication of unexpected data in the secure | +| | memory | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #979`_ (merged on 14 June 2017) | ++----------------+-------------------------------------------------------------+ +| Credit | ARM | ++----------------+-------------------------------------------------------------+ + +The ``include/lib/utils_def.h`` header file provides the +``check_uptr_overflow()`` macro, which aims at detecting arithmetic overflows +that may occur when computing the sum of a base pointer and an offset. This +macro evaluates to 1 if the sum of the given base pointer and offset would +result in a value large enough to wrap around, which may lead to unpredictable +behaviour. + +The macro code is at line 52, referring to the version of the code as of `commit +c396b73`_: + +.. code:: c + + /* + * Evaluates to 1 if (ptr + inc) overflows, 0 otherwise. + * Both arguments must be unsigned pointer values (i.e. uintptr_t). + */ + #define check_uptr_overflow(ptr, inc) \ + (((ptr) > UINTPTR_MAX - (inc)) ? 1 : 0) + +This macro does not work correctly for AArch32 images. It fails to detect +overflows when the sum of its two parameters fall into the ``[2^32, 2^64 - 1]`` +range. Therefore, any AArch32 code relying on this macro to detect such integer +overflows is actually not protected. + +The buggy code has been present in ARM Trusted Firmware (TF) since `Pull Request +#678`_ was merged (on 18 August 2016). However, the upstream code was not +vulnerable until `Pull Request #939`_ was merged (on 22 May 2017), which +introduced AArch32 support for the Trusted Board Boot (TBB) feature. Before +then, the ``check_uptr_overflow()`` macro was not used in AArch32 code. + +The vulnerability resides in the BL1 FWU SMC handling code and it may be +exploited when *all* the following conditions apply: + +- Platform code uses TF BL1 with the ``TRUSTED_BOARD_BOOT`` build option. + +- Platform code uses the Firmware Update (FWU) code provided in + ``bl1/bl1_fwu.c``, which is part of the TBB support. + +- TF BL1 is compiled with the ``ARCH=aarch32`` build option. + +In this context, the AArch32 BL1 image might fail to detect potential integer +overflows in the input validation checks while handling the +``FWU_SMC_IMAGE_COPY`` and ``FWU_SMC_IMAGE_AUTH`` SMCs. + +The ``FWU_SMC_IMAGE_COPY`` SMC handler is designed to copy an image into secure +memory for subsequent authentication. This is implemented by the +``bl1_fwu_image_copy()`` function, which has the following function prototype: + +.. code:: c + + static int bl1_fwu_image_copy(unsigned int image_id, + uintptr_t image_src, + unsigned int block_size, + unsigned int image_size, + unsigned int flags) + +``image_src`` is an SMC argument and therefore potentially controllable by an +attacker. A very large 32-bit value, for example ``2^32 -1``, may result in the +sum of ``image_src`` and ``block_size`` overflowing a 32-bit type, which +``check_uptr_overflow()`` will fail to detect. Depending on its implementation, +the platform-specific function ``bl1_plat_mem_check()`` might get defeated by +these unsanitized values and allow the following memory copy operation, that +would wrap around. This may allow an attacker to copy unexpected data into +secure memory if the memory is mapped in BL1's address space, or cause a fatal +exception if it's not. + +The ``FWU_SMC_IMAGE_AUTH`` SMC handler is designed to authenticate an image +resident in secure memory. This is implemented by the ``bl1_fwu_image_auth()`` +function, which has the following function prototype: + +.. code:: c + + static int bl1_fwu_image_auth(unsigned int image_id, + uintptr_t image_src, + unsigned int image_size, + unsigned int flags) + +Similarly, if an attacker has control over the ``image_src`` or ``image_size`` +arguments through the SMC interface and injects high values whose sum overflows, +they might defeat the ``bl1_plat_mem_check()`` function and make the +authentication module read data outside of what's normally allowed by the +platform code or crash the platform. + +Note that in both cases, a separate vulnerability is required to leverage this +vulnerability; for example a way to get the system to change its behaviour based +on the unexpected secure memory accesses. Moreover, the normal world FWU code +would need to be compromised in order to send a malformed FWU SMC that triggers +an integer overflow. + +The vulnerability is known to affect all ARM standard platforms when enabling +the ``TRUSTED_BOARD_BOOT`` and ``ARCH=aarch32`` build options. Other platforms +may also be affected if they fulfil the above conditions. + +.. _commit c396b73: https://github.com/ARM-software/arm-trusted-firmware/commit/c396b73 +.. _Pull Request #678: https://github.com/ARM-software/arm-trusted-firmware/pull/678 +.. _Pull Request #939: https://github.com/ARM-software/arm-trusted-firmware/pull/939 +.. _Pull Request #979: https://github.com/ARM-software/arm-trusted-firmware/pull/979 diff --git a/docs/security_advisories/security-advisory-tfv-5.rst b/docs/security_advisories/security-advisory-tfv-5.rst new file mode 100644 index 0000000..6525645 --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-5.rst @@ -0,0 +1,42 @@ ++----------------+-------------------------------------------------------------+ +| Title | Not initializing or saving/restoring ``PMCR_EL0`` can leak | +| | secure world timing information | ++================+=============================================================+ +| CVE ID | CVE-2017-15031 | ++----------------+-------------------------------------------------------------+ +| Date | 02 Oct 2017 | ++----------------+-------------------------------------------------------------+ +| Versions | All, up to and including v1.4 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | All | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Impact | Leakage of sensitive secure world timing information | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #1127`_ (merged on 18 October 2017) | ++----------------+-------------------------------------------------------------+ +| Credit | Arm | ++----------------+-------------------------------------------------------------+ + +The ``PMCR_EL0`` (Performance Monitors Control Register) provides details of the +Performance Monitors implementation, including the number of counters +implemented, and configures and controls the counters. If the ``PMCR_EL0.DP`` +bit is set to zero, the cycle counter (when enabled) counts during secure world +execution, even when prohibited by the debug signals. + +Since Arm TF does not save and restore ``PMCR_EL0`` when switching between the +normal and secure worlds, normal world code can set ``PMCR_EL0.DP`` to zero to +cause leakage of secure world timing information. This register should be added +to the list of saved/restored registers. + +Furthermore, ``PMCR_EL0.DP`` has an architecturally ``UNKNOWN`` reset value. +Since Arm TF does not initialize this register, it's possible that on at least +some implementations, ``PMCR_EL0.DP`` is set to zero by default. This and other +bits with an architecturally UNKNOWN reset value should be initialized to +sensible default values in the secure context. + +The same issue exists for the equivalent AArch32 register, ``PMCR``, except that +here ``PMCR_EL0.DP`` architecturally resets to zero. + +.. _Pull Request #1127: https://github.com/ARM-software/arm-trusted-firmware/pull/1127 diff --git a/docs/security_advisories/security-advisory-tfv-6.rst b/docs/security_advisories/security-advisory-tfv-6.rst new file mode 100644 index 0000000..7b556d8 --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-6.rst @@ -0,0 +1,145 @@ ++----------------+-------------------------------------------------------------+ +| Title | Arm Trusted Firmware exposure to speculative processor | +| | vulnerabilities using cache timing side-channels | ++================+=============================================================+ +| CVE ID | `CVE-2017-5753`_ / `CVE-2017-5715`_ / `CVE-2017-5754`_ | ++----------------+-------------------------------------------------------------+ +| Date | 03 Jan 2018 (Updated 11 Jan, 18 Jan, 26 Jan, 30 Jan and 07 | +| | June 2018) | ++----------------+-------------------------------------------------------------+ +| Versions | All, up to and including v1.4 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | All | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Impact | Leakage of secure world data to normal world | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #1214`_, `Pull Request #1228`_, | +| | `Pull Request #1240`_ and `Pull Request #1405`_ | ++----------------+-------------------------------------------------------------+ +| Credit | Google / Arm | ++----------------+-------------------------------------------------------------+ + +This security advisory describes the current understanding of the Arm Trusted +Firmware (TF) exposure to the speculative processor vulnerabilities identified +by `Google Project Zero`_. To understand the background and wider impact of +these vulnerabilities on Arm systems, please refer to the `Arm Processor +Security Update`_. + +Variant 1 (`CVE-2017-5753`_) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At the time of writing, no vulnerable patterns have been observed in upstream TF +code, therefore no workarounds have been applied or are planned. + +Variant 2 (`CVE-2017-5715`_) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Where possible on vulnerable CPUs, Arm recommends invalidating the branch +predictor as early as possible on entry into the secure world, before any branch +instruction is executed. There are a number of implementation defined ways to +achieve this. + +For Cortex-A57 and Cortex-A72 CPUs, the Pull Requests (PRs) in this advisory +invalidate the branch predictor when entering EL3 by disabling and re-enabling +the MMU. + +For Cortex-A73 and Cortex-A75 CPUs, the PRs in this advisory invalidate the +branch predictor when entering EL3 by temporarily dropping into AArch32 +Secure-EL1 and executing the ``BPIALL`` instruction. This workaround is +signifiantly more complex than the "MMU disable/enable" workaround. The latter +is not effective at invalidating the branch predictor on Cortex-A73/Cortex-A75. + +Note that if other privileged software, for example a Rich OS kernel, implements +its own branch predictor invalidation during context switch by issuing an SMC +(to execute firmware branch predictor invalidation), then there is a dependency +on the PRs in this advisory being deployed in order for those workarounds to +work. If that other privileged software is able to workaround the vulnerability +locally (for example by implementing "MMU disable/enable" itself), there is no +such dependency. + +`Pull Request #1240`_ and `Pull Request #1405`_ optimise the earlier fixes by +implementing a specified `CVE-2017-5715`_ workaround SMC +(``SMCCC_ARCH_WORKAROUND_1``) for use by normal world privileged software. This +is more efficient than calling an arbitrary SMC (for example ``PSCI_VERSION``). +Details of ``SMCCC_ARCH_WORKAROUND_1`` can be found in the `CVE-2017-5715 +mitigation specification`_. The specification and implementation also enable +the normal world to discover the presence of this firmware service. + +On Juno R1 we measured the round trip latency for both the ``PSCI_VERSION`` and +``SMCCC_ARCH_WORKAROUND_1`` SMCs on Cortex-A57, using both the "MMU +disable/enable" and "BPIALL at AArch32 Secure-EL1" workarounds described above. +This includes the time spent in test code conforming to the SMC Calling +Convention (SMCCC) from AArch64. For the ``SMCCC_ARCH_WORKAROUND_1`` cases, the +test code uses SMCCC v1.1, which reduces the number of general purpose registers +it needs to save/restore. Although the ``BPIALL`` instruction is not effective +at invalidating the branch predictor on Cortex-A57, the drop into Secure-EL1 +with MMU disabled that this workaround entails effectively does invalidate the +branch predictor. Hence this is a reasonable comparison. + +The results were as follows: + ++------------------------------------------------------------------+-----------+ +| Test | Time (ns) | ++==================================================================+===========+ +| ``PSCI_VERSION`` baseline (without PRs in this advisory) | 515 | ++------------------------------------------------------------------+-----------+ +| ``PSCI_VERSION`` baseline (with PRs in this advisory) | 527 | ++------------------------------------------------------------------+-----------+ +| ``PSCI_VERSION`` with "MMU disable/enable" | 930 | ++------------------------------------------------------------------+-----------+ +| ``SMCCC_ARCH_WORKAROUND_1`` with "MMU disable/enable" | 386 | ++------------------------------------------------------------------+-----------+ +| ``PSCI_VERSION`` with "BPIALL at AArch32 Secure-EL1" | 1276 | ++------------------------------------------------------------------+-----------+ +| ``SMCCC_ARCH_WORKAROUND_1`` with "BPIALL at AArch32 Secure-EL1" | 770 | ++------------------------------------------------------------------+-----------+ + +Due to the high severity and wide applicability of this issue, the above +workarounds are enabled by default (on vulnerable CPUs only), despite some +performance and code size overhead. Platforms can choose to disable them at +compile time if they do not require them. `Pull Request #1240`_ disables the +workarounds for unaffected upstream platforms. + +For vulnerable AArch32-only CPUs (for example Cortex-A8, Cortex-A9 and +Cortex-A17), the ``BPIALL`` instruction should be used as early as possible on +entry into the secure world. For Cortex-A8, also set ``ACTLR[6]`` to 1 during +early processor initialization. Note that the ``BPIALL`` instruction is not +effective at invalidating the branch predictor on Cortex-A15. For that CPU, set +``ACTLR[0]`` to 1 during early processor initialization, and invalidate the +branch predictor by performing an ``ICIALLU`` instruction. + +On AArch32 EL3 systems, the monitor and secure-SVC code is typically tightly +integrated, for example as part of a Trusted OS. Therefore any Variant 2 +workaround should be provided by vendors of that software and is outside the +scope of TF. However, an example implementation in the minimal AArch32 Secure +Payload, ``SP_MIN`` is provided in `Pull Request #1228`_. + +Other Arm CPUs are not vulnerable to this or other variants. This includes +Cortex-A76, Cortex-A53, Cortex-A55, Cortex-A32, Cortex-A7 and Cortex-A5. + +For more information about non-Arm CPUs, please contact the CPU vendor. + +Variant 3 (`CVE-2017-5754`_) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This variant is only exploitable between Exception Levels within the same +translation regime, for example between EL0 and EL1, therefore this variant +cannot be used to access secure memory from the non-secure world, and is not +applicable for TF. However, Secure Payloads (for example, Trusted OS) should +provide mitigations on vulnerable CPUs to protect themselves from exploited +Secure-EL0 applications. + +The only Arm CPU vulnerable to this variant is Cortex-A75. + +.. _Google Project Zero: https://googleprojectzero.blogspot.co.uk/2018/01/reading-privileged-memory-with-side.html +.. _Arm Processor Security Update: http://www.arm.com/security-update +.. _CVE-2017-5753: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5753 +.. _CVE-2017-5715: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5715 +.. _CVE-2017-5754: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2017-5754 +.. _Pull Request #1214: https://github.com/ARM-software/arm-trusted-firmware/pull/1214 +.. _Pull Request #1228: https://github.com/ARM-software/arm-trusted-firmware/pull/1228 +.. _Pull Request #1240: https://github.com/ARM-software/arm-trusted-firmware/pull/1240 +.. _Pull Request #1405: https://github.com/ARM-software/arm-trusted-firmware/pull/1405 +.. _CVE-2017-5715 mitigation specification: https://developer.arm.com/cache-speculation-vulnerability-firmware-specification diff --git a/docs/security_advisories/security-advisory-tfv-7.rst b/docs/security_advisories/security-advisory-tfv-7.rst new file mode 100644 index 0000000..572268a --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-7.rst @@ -0,0 +1,104 @@ ++----------------+-------------------------------------------------------------+ +| Title | Trusted Firmware-A exposure to cache speculation | +| | vulnerability Variant 4 | ++================+=============================================================+ +| CVE ID | `CVE-2018-3639`_ | ++----------------+-------------------------------------------------------------+ +| Date | 21 May 2018 (Updated 7 June 2018) | ++----------------+-------------------------------------------------------------+ +| Versions | All, up to and including v1.5 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | All | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Impact | Leakage of secure world data to normal world | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #1392`_, `Pull Request #1397`_ | ++----------------+-------------------------------------------------------------+ +| Credit | Google | ++----------------+-------------------------------------------------------------+ + +This security advisory describes the current understanding of the Trusted +Firmware-A (TF-A) exposure to Variant 4 of the cache speculation vulnerabilities +identified by `Google Project Zero`_. To understand the background and wider +impact of these vulnerabilities on Arm systems, please refer to the `Arm +Processor Security Update`_. + +At the time of writing, the TF-A project is not aware of a Variant 4 exploit +that could be used against TF-A. It is likely to be very difficult to achieve an +exploit against current standard configurations of TF-A, due to the limited +interfaces into the secure world with attacker-controlled inputs. However, this +is becoming increasingly difficult to guarantee with the introduction of complex +new firmware interfaces, for example the `Software Delegated Exception Interface +(SDEI)`_. Also, the TF-A project does not have visibility of all +vendor-supplied interfaces. Therefore, the TF-A project takes a conservative +approach by mitigating Variant 4 in hardware wherever possible during secure +world execution. The mitigation is enabled by setting an implementation defined +control bit to prevent the re-ordering of stores and loads. + +For each affected CPU type, TF-A implements one of the two following mitigation +approaches in `Pull Request #1392`_ and `Pull Request #1397`_. Both approaches +have a system performance impact, which varies for each CPU type and use-case. +The mitigation code is enabled by default, but can be disabled at compile time +for platforms that are unaffected or where the risk is deemed low enough. + +Arm CPUs not mentioned below are unaffected. + +Static mitigation +~~~~~~~~~~~~~~~~~ + +For affected CPUs, this approach enables the mitigation during EL3 +initialization, following every PE reset. No mechanism is provided to disable +the mitigation at runtime. + +This approach permanently mitigates the entire software stack and no additional +mitigation code is required in other software components. + +TF-A implements this approach for the following affected CPUs: + +- Cortex-A57 and Cortex-A72, by setting bit 55 (Disable load pass store) of + ``CPUACTLR_EL1`` (``S3_1_C15_C2_0``). + +- Cortex-A73, by setting bit 3 of ``S3_0_C15_C0_0`` (not documented in the + Technical Reference Manual (TRM)). + +- Cortex-A75, by setting bit 35 (reserved in TRM) of ``CPUACTLR_EL1`` + (``S3_0_C15_C1_0``). + +Dynamic mitigation +~~~~~~~~~~~~~~~~~~ + +For affected CPUs, this approach also enables the mitigation during EL3 +initialization, following every PE reset. In addition, this approach implements +``SMCCC_ARCH_WORKAROUND_2`` in the Arm architectural range to allow callers at +lower exception levels to temporarily disable the mitigation in their execution +context, where the risk is deemed low enough. This approach enables mitigation +on entry to EL3, and restores the mitigation state of the lower exception level +on exit from EL3. For more information on this approach, see `Firmware +interfaces for mitigating cache speculation vulnerabilities`_. + +This approach may be complemented by additional mitigation code in other +software components, for example code that calls ``SMCCC_ARCH_WORKAROUND_2``. +However, even without any mitigation code in other software components, this +approach will effectively permanently mitigate the entire software stack, since +the default mitigation state for firmware-managed execution contexts is enabled. + +Since the expectation in this approach is that more software executes with the +mitigation disabled, this may result in better system performance than the +static approach for some systems or use-cases. However, for other systems or +use-cases, this performance saving may be outweighed by the additional overhead +of ``SMCCC_ARCH_WORKAROUND_2`` calls and TF-A exception handling. + +TF-A implements this approach for the following affected CPU: + +- Cortex-A76, by setting and clearing bit 16 (reserved in TRM) of + ``CPUACTLR2_EL1`` (``S3_0_C15_C1_1``). + +.. _Google Project Zero: https://bugs.chromium.org/p/project-zero/issues/detail?id=1528 +.. _Arm Processor Security Update: http://www.arm.com/security-update +.. _CVE-2018-3639: http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-3639 +.. _Software Delegated Exception Interface (SDEI): http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf +.. _Firmware interfaces for mitigating cache speculation vulnerabilities: https://developer.arm.com/cache-speculation-vulnerability-firmware-specification +.. _Pull Request #1392: https://github.com/ARM-software/arm-trusted-firmware/pull/1392 +.. _Pull Request #1397: https://github.com/ARM-software/arm-trusted-firmware/pull/1397 diff --git a/docs/security_advisories/security-advisory-tfv-8.rst b/docs/security_advisories/security-advisory-tfv-8.rst new file mode 100644 index 0000000..d04c575 --- /dev/null +++ b/docs/security_advisories/security-advisory-tfv-8.rst @@ -0,0 +1,99 @@ ++----------------+-------------------------------------------------------------+ +| Title | Not saving x0 to x3 registers can leak information from one | +| | Normal World SMC client to another | ++================+=============================================================+ +| CVE ID | CVE-2018-19440 | ++----------------+-------------------------------------------------------------+ +| Date | 27 Nov 2018 | ++----------------+-------------------------------------------------------------+ +| Versions | All | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Configurations | Multiple normal world SMC clients calling into AArch64 BL31 | +| Affected | | ++----------------+-------------------------------------------------------------+ +| Impact | Leakage of SMC return values from one normal world SMC | +| | client to another | ++----------------+-------------------------------------------------------------+ +| Fix Version | `Pull Request #1710`_ | ++----------------+-------------------------------------------------------------+ +| Credit | Secmation | ++----------------+-------------------------------------------------------------+ + +When taking an exception to EL3, BL31 saves the CPU context. The aim is to +restore it before returning into the lower exception level software that called +into the firmware. However, for an SMC exception, the general purpose registers +``x0`` to ``x3`` are not part of the CPU context saved on the stack. + +As per the `SMC Calling Convention`_, up to 4 values may be returned to the +caller in registers ``x0`` to ``x3``. In TF-A, these return values are written +into the CPU context, typically using one of the ``SMC_RETx()`` macros provided +in the ``include/lib/aarch64/smccc_helpers.h`` header file. + +Before returning to the caller, the ``restore_gp_registers()`` function is +called. It restores the values of all general purpose registers taken from the +CPU context stored on the stack. This includes registers ``x0`` to ``x3``, as +can be seen in the ``lib/el3_runtime/aarch64/context.S`` file at line 339 +(referring to the version of the code as of `commit c385955`_): + +.. code:: c + + /* + * This function restores all general purpose registers except x30 from the + * CPU context. x30 register must be explicitly restored by the caller. + */ + func restore_gp_registers + ldp x0, x1, [sp, #CTX_GPREGS_OFFSET + CTX_GPREG_X0] + ldp x2, x3, [sp, #CTX_GPREGS_OFFSET + CTX_GPREG_X2] + +In the case of an SMC handler that does not use all 4 return values, the +remaining ones are left unchanged in the CPU context. As a result, +``restore_gp_registers()`` restores the stale values saved by a previous SMC +request (or asynchronous exception to EL3) that used these return values. + +In the presence of multiple normal world SMC clients, this behaviour might leak +some of the return values from one client to another. For example, if a victim +client first sends an SMC that returns 4 values, a malicious client may then +send a second SMC expecting no return values (for example, a +``SDEI_EVENT_COMPLETE`` SMC) to get the 4 return values of the victim client. + +In general, the responsibility for mitigating threats due to the presence of +multiple normal world SMC clients lies with EL2 software. When present, EL2 +software must trap SMC calls from EL1 software to ensure secure behaviour. + +For this reason, TF-A does not save ``x0`` to ``x3`` in the CPU context on an +SMC synchronous exception. It has behaved this way since the first version. + +We can confirm that at least upstream KVM-based systems mitigate this threat, +and are therefore unaffected by this issue. Other EL2 software should be audited +to assess the impact of this threat. + +EL2 software might find mitigating this threat somewhat onerous, because for all +SMCs it would need to be aware of which return registers contain valid data, so +it can sanitise any unused return registers. On the other hand, mitigating this +in EL3 is relatively easy and cheap. Therefore, TF-A will now ensure that no +information is leaked through registers ``x0`` to ``x3``, by preserving the +register state over the call. + +Note that AArch32 TF-A is not affected by this issue. The SMC handling code in +``SP_MIN`` already saves all general purpose registers - including ``r0`` to +``r3``, as can be seen in the ``include/lib/aarch32/smccc_macros.S`` file at +line 19 (referring to the version of the code as of `commit c385955`_): + +.. code:: c + + /* + * Macro to save the General purpose registers (r0 - r12), the banked + * spsr, lr, sp registers and the `scr` register to the SMC context on entry + * due a SMC call. The `lr` of the current mode (monitor) is expected to be + * already saved. The `sp` must point to the `smc_ctx_t` to save to. + * Additionally, also save the 'pmcr' register as this is updated whilst + * executing in the secure world. + */ + .macro smccc_save_gp_mode_regs + /* Save r0 - r12 in the SMC context */ + stm sp, {r0-r12} + +.. _commit c385955: https://github.com/ARM-software/arm-trusted-firmware/commit/c385955 +.. _SMC Calling Convention: http://arminfo.emea.arm.com/help/topic/com.arm.doc.den0028b/ARM_DEN0028B_SMC_Calling_Convention.pdf +.. _Pull Request #1710: https://github.com/ARM-software/arm-trusted-firmware/pull/1710