mirror of
https://mirrors.bfsu.edu.cn/git/linux.git
synced 2024-11-27 06:04:23 +08:00
50709576d8
Add a separate documentation directory for TEE subsystem since it is a standalone subsystem which already offers devices consumed by multiple different subsystem drivers. Split overall TEE subsystem documentation modularly where: - The userspace API has been moved to Documentation/userspace-api/tee.rst. - The driver API has been moved to Documentation/driver-api/tee.rst. - The first module covers the overview of TEE subsystem. - The further modules are dedicated to different TEE implementations like: - OP-TEE - AMD-TEE - and so on for future TEE implementation support. Acked-by: Rijo Thomas <Rijo-john.Thomas@amd.com> Acked-by: Jens Wiklander <jens.wiklander@linaro.org> Signed-off-by: Sumit Garg <sumit.garg@linaro.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20231128072352.866859-1-sumit.garg@linaro.org
167 lines
7.3 KiB
ReStructuredText
167 lines
7.3 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
====================================================
|
|
OP-TEE (Open Portable Trusted Execution Environment)
|
|
====================================================
|
|
|
|
The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
|
|
TrustZone based OP-TEE solution that is supported.
|
|
|
|
Lowest level of communication with OP-TEE builds on ARM SMC Calling
|
|
Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
|
|
[3] used internally by the driver. Stacked on top of that is OP-TEE Message
|
|
Protocol [4].
|
|
|
|
OP-TEE SMC interface provides the basic functions required by SMCCC and some
|
|
additional functions specific for OP-TEE. The most interesting functions are:
|
|
|
|
- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
|
|
which is then returned by TEE_IOC_VERSION
|
|
|
|
- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
|
|
to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
|
|
separate secure co-processor.
|
|
|
|
- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
|
|
|
|
- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
|
|
range to used for shared memory between Linux and OP-TEE.
|
|
|
|
The GlobalPlatform TEE Client API [5] is implemented on top of the generic
|
|
TEE API.
|
|
|
|
Picture of the relationship between the different components in the
|
|
OP-TEE architecture::
|
|
|
|
User space Kernel Secure world
|
|
~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
|
|
+--------+ +-------------+
|
|
| Client | | Trusted |
|
|
+--------+ | Application |
|
|
/\ +-------------+
|
|
|| +----------+ /\
|
|
|| |tee- | ||
|
|
|| |supplicant| \/
|
|
|| +----------+ +-------------+
|
|
\/ /\ | TEE Internal|
|
|
+-------+ || | API |
|
|
+ TEE | || +--------+--------+ +-------------+
|
|
| Client| || | TEE | OP-TEE | | OP-TEE |
|
|
| API | \/ | subsys | driver | | Trusted OS |
|
|
+-------+----------------+----+-------+----+-----------+-------------+
|
|
| Generic TEE API | | OP-TEE MSG |
|
|
| IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
|
|
+-----------------------------+ +------------------------------+
|
|
|
|
RPC (Remote Procedure Call) are requests from secure world to kernel driver
|
|
or tee-supplicant. An RPC is identified by a special range of SMCCC return
|
|
values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
|
|
kernel are handled by the kernel driver. Other RPC messages will be forwarded to
|
|
tee-supplicant without further involvement of the driver, except switching
|
|
shared memory buffer representation.
|
|
|
|
OP-TEE device enumeration
|
|
-------------------------
|
|
|
|
OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in
|
|
order to support device enumeration. In other words, OP-TEE driver invokes this
|
|
application to retrieve a list of Trusted Applications which can be registered
|
|
as devices on the TEE bus.
|
|
|
|
OP-TEE notifications
|
|
--------------------
|
|
|
|
There are two kinds of notifications that secure world can use to make
|
|
normal world aware of some event.
|
|
|
|
1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION``
|
|
using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter.
|
|
2. Asynchronous notifications delivered with a combination of a non-secure
|
|
edge-triggered interrupt and a fast call from the non-secure interrupt
|
|
handler.
|
|
|
|
Synchronous notifications are limited by depending on RPC for delivery,
|
|
this is only usable when secure world is entered with a yielding call via
|
|
``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure
|
|
world interrupt handlers.
|
|
|
|
An asynchronous notification is delivered via a non-secure edge-triggered
|
|
interrupt to an interrupt handler registered in the OP-TEE driver. The
|
|
actual notification value are retrieved with the fast call
|
|
``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent
|
|
multiple notifications.
|
|
|
|
One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a
|
|
special meaning. When this value is received it means that normal world is
|
|
supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This
|
|
call is done from the thread assisting the interrupt handler. This is a
|
|
building block for OP-TEE OS in secure world to implement the top half and
|
|
bottom half style of device drivers.
|
|
|
|
OPTEE_INSECURE_LOAD_IMAGE Kconfig option
|
|
----------------------------------------
|
|
|
|
The OPTEE_INSECURE_LOAD_IMAGE Kconfig option enables the ability to load the
|
|
BL32 OP-TEE image from the kernel after the kernel boots, rather than loading
|
|
it from the firmware before the kernel boots. This also requires enabling the
|
|
corresponding option in Trusted Firmware for Arm. The Trusted Firmware for Arm
|
|
documentation [6] explains the security threat associated with enabling this as
|
|
well as mitigations at the firmware and platform level.
|
|
|
|
There are additional attack vectors/mitigations for the kernel that should be
|
|
addressed when using this option.
|
|
|
|
1. Boot chain security.
|
|
|
|
* Attack vector: Replace the OP-TEE OS image in the rootfs to gain control of
|
|
the system.
|
|
|
|
* Mitigation: There must be boot chain security that verifies the kernel and
|
|
rootfs, otherwise an attacker can modify the loaded OP-TEE binary by
|
|
modifying it in the rootfs.
|
|
|
|
2. Alternate boot modes.
|
|
|
|
* Attack vector: Using an alternate boot mode (i.e. recovery mode), the
|
|
OP-TEE driver isn't loaded, leaving the SMC hole open.
|
|
|
|
* Mitigation: If there are alternate methods of booting the device, such as a
|
|
recovery mode, it should be ensured that the same mitigations are applied
|
|
in that mode.
|
|
|
|
3. Attacks prior to SMC invocation.
|
|
|
|
* Attack vector: Code that is executed prior to issuing the SMC call to load
|
|
OP-TEE can be exploited to then load an alternate OS image.
|
|
|
|
* Mitigation: The OP-TEE driver must be loaded before any potential attack
|
|
vectors are opened up. This should include mounting of any modifiable
|
|
filesystems, opening of network ports or communicating with external
|
|
devices (e.g. USB).
|
|
|
|
4. Blocking SMC call to load OP-TEE.
|
|
|
|
* Attack vector: Prevent the driver from being probed, so the SMC call to
|
|
load OP-TEE isn't executed when desired, leaving it open to being executed
|
|
later and loading a modified OS.
|
|
|
|
* Mitigation: It is recommended to build the OP-TEE driver as builtin driver
|
|
rather than as a module to prevent exploits that may cause the module to
|
|
not be loaded.
|
|
|
|
References
|
|
==========
|
|
|
|
[1] https://github.com/OP-TEE/optee_os
|
|
|
|
[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
|
|
|
|
[3] drivers/tee/optee/optee_smc.h
|
|
|
|
[4] drivers/tee/optee/optee_msg.h
|
|
|
|
[5] http://www.globalplatform.org/specificationsdevice.asp look for
|
|
"TEE Client API Specification v1.0" and click download.
|
|
|
|
[6] https://trustedfirmware-a.readthedocs.io/en/latest/threat_model/threat_model.html
|