← Documents Documentation/tee/op-tee.rst GitHub 원문 ↗

Linux 6.18.37 · TEE

OP-TEE (Open Portable Trusted Execution Environment)

OP-TEE의 SMCCC·message protocol 계층, RPC, device enumeration, 동기·비동기 notification과 insecure image load의 보안 조건을 설명합니다.

Source pathDocumentation/tee/op-tee.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약·해설

op-tee.rst:1-166

OP-TEE의 SMCCC·message protocol 계층, RPC, device enumeration, 동기·비동기 notification과 insecure image load의 보안 조건을 설명합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
1 .. SPDX-License-Identifier: GPL-2.0
2
3 ====================================================
4 OP-TEE (Open Portable Trusted Execution Environment)
5 ====================================================
6
7 The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
8 TrustZone based OP-TEE solution that is supported.
9
10 Lowest level of communication with OP-TEE builds on ARM SMC Calling
11 Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
12 [3] used internally by the driver. Stacked on top of that is OP-TEE Message
13 Protocol [4].
14
15 OP-TEE SMC interface provides the basic functions required by SMCCC and some
16 additional functions specific for OP-TEE. The most interesting functions are:
17
18 - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
19 which is then returned by TEE_IOC_VERSION
20
21 - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
22 to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
23 separate secure co-processor.
24
25 - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
26
27 - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
28 range to used for shared memory between Linux and OP-TEE.
29
30 The GlobalPlatform TEE Client API [5] is implemented on top of the generic
31 TEE API.
32
33 Picture of the relationship between the different components in the
34 OP-TEE architecture::
35
36 User space Kernel Secure world
37 ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
38 +--------+ +-------------+
39 | Client | | Trusted |
40 +--------+ | Application |
41 /\ +-------------+
42 || +----------+ /\
43 || |tee- | ||
44 || |supplicant| \/
45 || +----------+ +-------------+
46 \/ /\ | TEE Internal|
47 +-------+ || | API |
48 + TEE | || +--------+--------+ +-------------+
49 | Client| || | TEE | OP-TEE | | OP-TEE |
50 | API | \/ | subsys | driver | | Trusted OS |
51 +-------+----------------+----+-------+----+-----------+-------------+
52 | Generic TEE API | | OP-TEE MSG |
53 | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
54 +-----------------------------+ +------------------------------+
55
56 RPC (Remote Procedure Call) are requests from secure world to kernel driver
57 or tee-supplicant. An RPC is identified by a special range of SMCCC return
58 values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
59 kernel are handled by the kernel driver. Other RPC messages will be forwarded to
60 tee-supplicant without further involvement of the driver, except switching
61 shared memory buffer representation.
62
63 OP-TEE device enumeration
64 -------------------------
65
66 OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in
67 order to support device enumeration. In other words, OP-TEE driver invokes this
68 application to retrieve a list of Trusted Applications which can be registered
69 as devices on the TEE bus.
70
71 OP-TEE notifications
72 --------------------
73
74 There are two kinds of notifications that secure world can use to make
75 normal world aware of some event.
76
77 1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION``
78 using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter.
79 2. Asynchronous notifications delivered with a combination of a non-secure
80 edge-triggered interrupt and a fast call from the non-secure interrupt
81 handler.
82
83 Synchronous notifications are limited by depending on RPC for delivery,
84 this is only usable when secure world is entered with a yielding call via
85 ``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure
86 world interrupt handlers.
87
88 An asynchronous notification is delivered via a non-secure edge-triggered
89 interrupt to an interrupt handler registered in the OP-TEE driver. The
90 actual notification value are retrieved with the fast call
91 ``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent
92 multiple notifications.
93
94 One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a
95 special meaning. When this value is received it means that normal world is
96 supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This
97 call is done from the thread assisting the interrupt handler. This is a
98 building block for OP-TEE OS in secure world to implement the top half and
99 bottom half style of device drivers.
100
101 OPTEE_INSECURE_LOAD_IMAGE Kconfig option
102 ----------------------------------------
103
104 The OPTEE_INSECURE_LOAD_IMAGE Kconfig option enables the ability to load the
105 BL32 OP-TEE image from the kernel after the kernel boots, rather than loading
106 it from the firmware before the kernel boots. This also requires enabling the
107 corresponding option in Trusted Firmware for Arm. The Trusted Firmware for Arm
108 documentation [6] explains the security threat associated with enabling this as
109 well as mitigations at the firmware and platform level.
110
111 There are additional attack vectors/mitigations for the kernel that should be
112 addressed when using this option.
113
114 1. Boot chain security.
115
116 * Attack vector: Replace the OP-TEE OS image in the rootfs to gain control of
117 the system.
118
119 * Mitigation: There must be boot chain security that verifies the kernel and
120 rootfs, otherwise an attacker can modify the loaded OP-TEE binary by
121 modifying it in the rootfs.
122
123 2. Alternate boot modes.
124
125 * Attack vector: Using an alternate boot mode (i.e. recovery mode), the
126 OP-TEE driver isn't loaded, leaving the SMC hole open.
127
128 * Mitigation: If there are alternate methods of booting the device, such as a
129 recovery mode, it should be ensured that the same mitigations are applied
130 in that mode.
131
132 3. Attacks prior to SMC invocation.
133
134 * Attack vector: Code that is executed prior to issuing the SMC call to load
135 OP-TEE can be exploited to then load an alternate OS image.
136
137 * Mitigation: The OP-TEE driver must be loaded before any potential attack
138 vectors are opened up. This should include mounting of any modifiable
139 filesystems, opening of network ports or communicating with external
140 devices (e.g. USB).
141
142 4. Blocking SMC call to load OP-TEE.
143
144 * Attack vector: Prevent the driver from being probed, so the SMC call to
145 load OP-TEE isn't executed when desired, leaving it open to being executed
146 later and loading a modified OS.
147
148 * Mitigation: It is recommended to build the OP-TEE driver as builtin driver
149 rather than as a module to prevent exploits that may cause the module to
150 not be loaded.
151
152 References
153 ==========
154
155 [1] https://github.com/OP-TEE/optee_os
156
157 [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
158
159 [3] drivers/tee/optee/optee_smc.h
160
161 [4] drivers/tee/optee/optee_msg.h
162
163 [5] http://www.globalplatform.org/specificationsdevice.asp look for
164 "TEE Client API Specification v1.0" and click download.
165
166 [6] https://trustedfirmware-a.readthedocs.io/en/latest/threat_model/threat_model.html
167

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

SMCCC, SMC interface와 message protocol

1-31

OP-TEE driver는 OP-TEE 기반 TEE를 처리하며, 현재 지원 대상은 ARM TrustZone 기반 OP-TEE solution이다.

OP-TEE와 통신하는 최하위 계층은 ARM SMC Calling Convention(SMCCC) `[2]`다. driver 내부의 OP-TEE SMC interface `[3]`가 그 위에 놓이고, 다시 OP-TEE Message Protocol `[4]`이 쌓인다. GlobalPlatform TEE Client API `[5]`는 generic TEE API 위에 구현된다.

`OPTEE_SMC_FUNCID_CALLS_UID`는 SMCCC 일부로 version 정보를 반환하며 이 정보가 `TEE_IOC_VERSION`의 결과가 된다. `OPTEE_SMC_CALL_GET_OS_UUID`는 특정 OP-TEE 구현을 식별해 TrustZone 구현과 별도 secure co-processor 구현 등을 구분한다.

`OPTEE_SMC_CALL_WITH_ARG`는 OP-TEE message protocol을 구동한다. `OPTEE_SMC_GET_SHM_CONFIG`는 Linux와 OP-TEE가 shared memory로 사용할 memory range를 합의하게 한다.

주요 OP-TEE SMC 함수
함수역할
OPTEE_SMC_FUNCID_CALLS_UIDversion 정보 반환; TEE_IOC_VERSION으로 전달
OPTEE_SMC_CALL_GET_OS_UUIDOP-TEE 구현 식별
OPTEE_SMC_CALL_WITH_ARGOP-TEE message protocol 구동
OPTEE_SMC_GET_SHM_CONFIGLinux와 OP-TEE 사이 shared memory 범위 합의

driver가 식별, message, shared memory 설정에 사용하는 함수다.

OP-TEE protocol stack
GlobalPlatform TEE Client APIGeneric TEE API
Generic TEE APIOP-TEE driverOP-TEE Message Protocol
OP-TEE Message ProtocolOP-TEE SMC interfaceSMCCCSecure world

상위 client API에서 secure world 호출까지의 계층이다.

.. 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.

OP-TEE 구성 요소와 RPC

32-62

user space의 client와 `tee-supplicant`는 generic TEE API를 통해 kernel의 TEE subsystem 및 OP-TEE driver와 연결된다. secure world에는 OP-TEE Trusted OS, TEE Internal API, Trusted Application이 있으며 OP-TEE MSG와 SMCCC 호출이 normal world와 secure world를 잇는다.

RPC(Remote Procedure Call)는 secure world가 kernel driver 또는 `tee-supplicant`에 보내는 요청이다. `OPTEE_SMC_CALL_WITH_ARG`가 반환하는 특별한 SMCCC 값 범위로 RPC를 식별한다.

kernel용 RPC message는 kernel driver가 직접 처리한다. 그 밖의 RPC message는 shared memory buffer 표현을 전환하는 작업을 제외하면 driver가 추가로 관여하지 않고 `tee-supplicant`로 전달한다.

OP-TEE 아키텍처
ClientTEE Client APIGeneric TEE API / TEE_IOC_*
tee-supplicantGeneric TEE API / TEE_IOC_*
Generic TEE API / TEE_IOC_*TEE subsystemOP-TEE driver
OP-TEE driverOP-TEE MSGSMCCCOP-TEE Trusted OS
OP-TEE Trusted OSTEE Internal APITrusted Application

원문의 ASCII 그림을 영역별 호출 흐름으로 재구성했다.

RPC 분기
대상처리 방식
KernelOP-TEE kernel driver가 직접 처리
tee-supplicantshared memory 표현을 바꾼 뒤 user space로 전달

SMCCC return value로 식별한 RPC의 목적지다.


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.

Device enumeration과 notification

63-100

OP-TEE는 device enumeration을 위해 `drivers/tee/optee/device.c`의 pseudo Trusted Application을 제공한다. OP-TEE driver가 이 application을 호출해 TEE bus device로 등록할 수 있는 Trusted Application 목록을 가져온다.

secure world가 normal world에 event를 알리는 notification에는 synchronous와 asynchronous 두 종류가 있다. synchronous notification은 `OPTEE_RPC_CMD_NOTIFICATION`과 `OPTEE_RPC_NOTIFICATION_SEND` parameter를 사용한다. asynchronous notification은 non-secure edge-triggered interrupt와 non-secure interrupt handler의 fast call을 조합한다.

synchronous notification은 RPC 전달에 의존하므로 `OPTEE_SMC_CALL_WITH_ARG` yielding call로 secure world에 진입한 경우에만 사용할 수 있다. 따라서 secure world interrupt handler에서는 사용할 수 없다.

asynchronous notification은 OP-TEE driver에 등록된 interrupt handler로 non-secure edge-triggered interrupt를 전달한다. 실제 notification 값은 fast call `OPTEE_SMC_GET_ASYNC_NOTIF_VALUE`로 가져오며, interrupt 하나가 여러 notification을 나타낼 수 있다.

`OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`는 특별한 값이다. 이 값을 받으면 normal world가 `OPTEE_MSG_CMD_DO_BOTTOM_HALF` yielding call을 수행해야 한다. interrupt handler를 보조하는 thread가 이 call을 실행하며, secure world의 OP-TEE OS가 top-half/bottom-half 방식 device driver를 구현하는 기반이 된다.

OP-TEE notification
종류전달제약 또는 의미
SynchronousOPTEE_RPC_CMD_NOTIFICATION + OPTEE_RPC_NOTIFICATION_SENDyielding call 진입 중에만 사용
Asynchronousedge-triggered interrupt + fast callinterrupt 하나가 여러 notification을 표현 가능
DO_BOTTOM_HALFOPTEE_MSG_CMD_DO_BOTTOM_HALF yielding callsecure-world driver bottom half 실행

전달 방식과 제약을 비교한다.

비동기 notification 처리
Non-secure edge interruptOP-TEE interrupt handler
OPTEE_SMC_GET_ASYNC_NOTIF_VALUEOne or more notification values
DO_BOTTOM_HALF valueHelper threadOPTEE_MSG_CMD_DO_BOTTOM_HALF

interrupt에서 실제 값과 bottom-half 요청을 분리한다.

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의 위협과 완화

101-150

`OPTEE_INSECURE_LOAD_IMAGE` Kconfig option은 firmware가 kernel boot 전에 BL32 OP-TEE image를 load하는 대신, kernel boot 후 kernel이 image를 load할 수 있게 한다. Trusted Firmware for Arm에서도 대응 option을 켜야 하며, `[6]`은 이 설정의 security threat와 firmware/platform 수준 완화를 설명한다.

boot chain 공격에서는 공격자가 rootfs의 OP-TEE OS image를 바꿔 system을 장악할 수 있다. kernel과 rootfs를 검증하는 secure boot chain이 없으면 load될 OP-TEE binary도 rootfs 변경으로 조작될 수 있으므로 둘을 모두 검증해야 한다.

recovery mode 같은 alternate boot mode에서 OP-TEE driver를 load하지 않으면 SMC 진입점이 열린 채 남을 수 있다. 장치가 다른 방식으로 boot될 수 있다면 모든 mode에 동일한 완화를 적용해야 한다.

OP-TEE load SMC를 호출하기 전에 실행되는 code가 공격당하면 대체 OS image를 load할 수 있다. 따라서 modifiable filesystem mount, network port open, USB 같은 external device 통신 등 잠재적 attack vector를 열기 전에 OP-TEE driver를 load해야 한다.

driver probe를 막아 예정된 시점의 load SMC 실행을 방해하면 공격자가 나중에 열린 SMC를 호출해 수정된 OS를 load할 수 있다. module load 자체를 방해하는 exploit 가능성을 줄이려면 OP-TEE driver를 module이 아니라 builtin driver로 build하는 것이 권장된다.

Kernel 측 공격 경로와 완화
항목공격 경로완화
Boot chainrootfs의 OP-TEE image 교체kernel과 rootfs를 함께 검증
Alternate bootrecovery mode에서 driver 미적재모든 boot mode에 같은 완화 적용
Pre-SMC codeSMC 전 code exploit으로 대체 image loadfilesystem/network/external I/O보다 먼저 driver load
Blocked probeprobe를 막아 SMC를 나중에 악용driver를 builtin으로 build

option 사용 시 추가로 다뤄야 하는 네 항목이다.

안전한 late load 순서
Verified kernel + rootfsBuiltin OP-TEE driver
Load and lock OP-TEE imageMount mutable filesystems
Open network or external device access

공격 표면을 열기 전에 OP-TEE를 확정해야 한다.

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.

OP-TEE interface 참고 자료

151-166

참고 자료는 OP-TEE OS repository, ARM SMCCC 문서, kernel의 `drivers/tee/optee/optee_smc.h`와 `optee_msg.h`, GlobalPlatform TEE Client API specification, Trusted Firmware for Arm threat model을 연결한다.

OP-TEE 참고 자료
참조내용
[1]OP-TEE OS source
[2]ARM SMC Calling Convention
[3] / [4]kernel SMC interface / message protocol header
[5]GlobalPlatform TEE Client API v1.0
[6]Trusted Firmware for Arm threat model

각 출처가 다루는 계층이다.


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