summaryrefslogtreecommitdiffstats
path: root/docs/process/security-hardening.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:13:47 +0000
commit102b0d2daa97dae68d3eed54d8fe37a9cc38a892 (patch)
treebcf648efac40ca6139842707f0eba5a4496a6dd2 /docs/process/security-hardening.rst
parentInitial commit. (diff)
downloadarm-trusted-firmware-102b0d2daa97dae68d3eed54d8fe37a9cc38a892.tar.xz
arm-trusted-firmware-102b0d2daa97dae68d3eed54d8fe37a9cc38a892.zip
Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'docs/process/security-hardening.rst')
-rw-r--r--docs/process/security-hardening.rst175
1 files changed, 175 insertions, 0 deletions
diff --git a/docs/process/security-hardening.rst b/docs/process/security-hardening.rst
new file mode 100644
index 0000000..507046f
--- /dev/null
+++ b/docs/process/security-hardening.rst
@@ -0,0 +1,175 @@
+Secure Development Guidelines
+=============================
+
+This page contains guidance on what to check for additional security measures,
+including build options that can be modified to improve security or catch issues
+early in development.
+
+Security considerations
+-----------------------
+
+Part of the security of a platform is handling errors correctly, as described in
+the previous section. There are several other security considerations covered in
+this section.
+
+Do not leak secrets to the normal world
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The secure world **must not** leak secrets to the normal world, for example in
+response to an SMC.
+
+Handling Denial of Service attacks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The secure world **should never** crash or become unusable due to receiving too
+many normal world requests (a *Denial of Service* or *DoS* attack). It should
+have a mechanism for throttling or ignoring normal world requests.
+
+Preventing Secure-world timing information leakage via PMU counters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Secure world needs to implement some defenses to prevent the Non-secure
+world from making it leak timing information. In general, higher privilege
+levels must defend from those below when the PMU is treated as an attack
+vector.
+
+Refer to the :ref:`Performance Monitoring Unit` guide for detailed information
+on the PMU registers.
+
+Timing leakage attacks from the Non-secure world
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since the Non-secure world has access to the ``PMCR`` register, it can
+configure the PMU to increment counters at any exception level and in both
+Secure and Non-secure state. Thus, it attempts to leak timing information from
+the Secure world.
+
+Shown below is an example of such a configuration:
+
+- ``PMEVTYPER0_EL0`` and ``PMCCFILTR_EL0``:
+
+ - Set ``P`` to ``0``.
+ - Set ``NSK`` to ``1``.
+ - Set ``M`` to ``0``.
+ - Set ``NSH`` to ``0``.
+ - Set ``SH`` to ``1``.
+
+- ``PMCNTENSET_EL0``:
+
+ - Set ``P[0]`` to ``1``.
+ - Set ``C`` to ``1``.
+
+- ``PMCR_EL0``:
+
+ - Set ``DP`` to ``0``.
+ - Set ``E`` to ``1``.
+
+This configuration instructs ``PMEVCNTR0_EL0`` and ``PMCCNTR_EL0`` to increment
+at Secure EL1, Secure EL2 (if implemented) and EL3.
+
+Since the Non-secure world has fine-grained control over where (at which
+exception levels) it instructs counters to increment, obtaining event counts
+would allow it to carry out side-channel timing attacks against the Secure
+world. Examples include Spectre, Meltdown, as well as extracting secrets from
+cryptographic algorithms with data-dependent variations in their execution
+time.
+
+Secure world mitigation strategies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``MDCR_EL3`` register allows EL3 to configure the PMU (among other things).
+The `Arm ARM`_ details all of the bit fields in this register, but for the PMU
+there are two bits which determine the permissions of the counters:
+
+- ``SPME`` for the programmable counters.
+- ``SCCD`` for the cycle counter.
+
+Depending on the implemented features, the Secure world can prohibit counting
+in AArch64 state via the following:
+
+- ARMv8.2-Debug not implemented:
+
+ - Prohibit general event counters and the cycle counter:
+ ``MDCR_EL3.SPME == 0 && PMCR_EL0.DP == 1 && !ExternalSecureNoninvasiveDebugEnabled()``.
+
+ - ``MDCR_EL3.SPME`` resets to ``0``, so by default general events should
+ not be counted in the Secure world.
+ - The ``PMCR_EL0.DP`` bit therefore needs to be set to ``1`` when EL3 is
+ entered and ``PMCR_EL0`` needs to be saved and restored in EL3.
+ - ``ExternalSecureNoninvasiveDebugEnabled()`` is an authentication
+ interface which is implementation-defined unless ARMv8.4-Debug is
+ implemented. The `Arm ARM`_ has detailed information on this topic.
+
+ - The only other way is to disable the ``PMCR_EL0.E`` bit upon entering
+ EL3, which disables counting altogether.
+
+- ARMv8.2-Debug implemented:
+
+ - Prohibit general event counters: ``MDCR_EL3.SPME == 0``.
+ - Prohibit cycle counter: ``MDCR_EL3.SPME == 0 && PMCR_EL0.DP == 1``.
+ ``PMCR_EL0`` therefore needs to be saved and restored in EL3.
+
+- ARMv8.5-PMU implemented:
+
+ - Prohibit general event counters: as in ARMv8.2-Debug.
+ - Prohibit cycle counter: ``MDCR_EL3.SCCD == 1``
+
+In Aarch32 execution state the ``MDCR_EL3`` alias is the ``SDCR`` register,
+which has some of the bit fields of ``MDCR_EL3``, most importantly the ``SPME``
+and ``SCCD`` bits.
+
+Build options
+-------------
+
+Several build options can be used to check for security issues. Refer to the
+:ref:`Build Options` for detailed information on these.
+
+- The ``BRANCH_PROTECTION`` build flag can be used to enable Pointer
+ Authentication and Branch Target Identification.
+
+- The ``ENABLE_STACK_PROTECTOR`` build flag can be used to identify buffer
+ overflows.
+
+- The ``W`` build flag can be used to enable a number of compiler warning
+ options to detect potentially incorrect code.
+
+ - W=0 (default value)
+
+ The ``Wunused`` with ``Wno-unused-parameter``, ``Wdisabled-optimization``
+ and ``Wvla`` flags are enabled.
+
+ The ``Wunused-but-set-variable``, ``Wmaybe-uninitialized`` and
+ ``Wpacked-bitfield-compat`` are GCC specific flags that are also enabled.
+
+ - W=1
+
+ Adds ``Wextra``, ``Wmissing-format-attribute``, ``Wmissing-prototypes``,
+ ``Wold-style-definition`` and ``Wunused-const-variable``.
+
+ - W=2
+
+ Adds ``Waggregate-return``, ``Wcast-align``, ``Wnested-externs``,
+ ``Wshadow``, ``Wlogical-op``.
+
+ - W=3
+
+ Adds ``Wbad-function-cast``, ``Wcast-qual``, ``Wconversion``, ``Wpacked``,
+ ``Wpointer-arith``, ``Wredundant-decls`` and
+ ``Wswitch-default``.
+
+ Refer to the GCC or Clang documentation for more information on the individual
+ options: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html and
+ https://clang.llvm.org/docs/DiagnosticsReference.html.
+
+ NB: The ``Werror`` flag is enabled by default in TF-A and can be disabled by
+ setting the ``E`` build flag to 0.
+
+.. rubric:: References
+
+- `Arm ARM`_
+
+--------------
+
+*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
+
+.. _Arm ARM: https://developer.arm.com/docs/ddi0487/latest