0001 =============
0002 TEE subsystem
0003 =============
0004
0005 This document describes the TEE subsystem in Linux.
0006
0007 A TEE (Trusted Execution Environment) is a trusted OS running in some
0008 secure environment, for example, TrustZone on ARM CPUs, or a separate
0009 secure co-processor etc. A TEE driver handles the details needed to
0010 communicate with the TEE.
0011
0012 This subsystem deals with:
0013
0014 - Registration of TEE drivers
0015
0016 - Managing shared memory between Linux and the TEE
0017
0018 - Providing a generic API to the TEE
0019
0020 The TEE interface
0021 =================
0022
0023 include/uapi/linux/tee.h defines the generic interface to a TEE.
0024
0025 User space (the client) connects to the driver by opening /dev/tee[0-9]* or
0026 /dev/teepriv[0-9]*.
0027
0028 - TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor
0029 which user space can mmap. When user space doesn't need the file
0030 descriptor any more, it should be closed. When shared memory isn't needed
0031 any longer it should be unmapped with munmap() to allow the reuse of
0032 memory.
0033
0034 - TEE_IOC_VERSION lets user space know which TEE this driver handles and
0035 its capabilities.
0036
0037 - TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application.
0038
0039 - TEE_IOC_INVOKE invokes a function in a Trusted Application.
0040
0041 - TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE.
0042
0043 - TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application.
0044
0045 There are two classes of clients, normal clients and supplicants. The latter is
0046 a helper process for the TEE to access resources in Linux, for example file
0047 system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
0048 /dev/teepriv[0-9].
0049
0050 Much of the communication between clients and the TEE is opaque to the
0051 driver. The main job for the driver is to receive requests from the
0052 clients, forward them to the TEE and send back the results. In the case of
0053 supplicants the communication goes in the other direction, the TEE sends
0054 requests to the supplicant which then sends back the result.
0055
0056 The TEE kernel interface
0057 ========================
0058
0059 Kernel provides a TEE bus infrastructure where a Trusted Application is
0060 represented as a device identified via Universally Unique Identifier (UUID) and
0061 client drivers register a table of supported device UUIDs.
0062
0063 TEE bus infrastructure registers following APIs:
0064
0065 match():
0066 iterates over the client driver UUID table to find a corresponding
0067 match for device UUID. If a match is found, then this particular device is
0068 probed via corresponding probe API registered by the client driver. This
0069 process happens whenever a device or a client driver is registered with TEE
0070 bus.
0071
0072 uevent():
0073 notifies user-space (udev) whenever a new device is registered on
0074 TEE bus for auto-loading of modularized client drivers.
0075
0076 TEE bus device enumeration is specific to underlying TEE implementation, so it
0077 is left open for TEE drivers to provide corresponding implementation.
0078
0079 Then TEE client driver can talk to a matched Trusted Application using APIs
0080 listed in include/linux/tee_drv.h.
0081
0082 TEE client driver example
0083 -------------------------
0084
0085 Suppose a TEE client driver needs to communicate with a Trusted Application
0086 having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration
0087 snippet would look like::
0088
0089 static const struct tee_client_device_id client_id_table[] = {
0090 {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33,
0091 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)},
0092 {}
0093 };
0094
0095 MODULE_DEVICE_TABLE(tee, client_id_table);
0096
0097 static struct tee_client_driver client_driver = {
0098 .id_table = client_id_table,
0099 .driver = {
0100 .name = DRIVER_NAME,
0101 .bus = &tee_bus_type,
0102 .probe = client_probe,
0103 .remove = client_remove,
0104 },
0105 };
0106
0107 static int __init client_init(void)
0108 {
0109 return driver_register(&client_driver.driver);
0110 }
0111
0112 static void __exit client_exit(void)
0113 {
0114 driver_unregister(&client_driver.driver);
0115 }
0116
0117 module_init(client_init);
0118 module_exit(client_exit);
0119
0120 OP-TEE driver
0121 =============
0122
0123 The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
0124 TrustZone based OP-TEE solution that is supported.
0125
0126 Lowest level of communication with OP-TEE builds on ARM SMC Calling
0127 Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
0128 [3] used internally by the driver. Stacked on top of that is OP-TEE Message
0129 Protocol [4].
0130
0131 OP-TEE SMC interface provides the basic functions required by SMCCC and some
0132 additional functions specific for OP-TEE. The most interesting functions are:
0133
0134 - OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
0135 which is then returned by TEE_IOC_VERSION
0136
0137 - OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
0138 to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
0139 separate secure co-processor.
0140
0141 - OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
0142
0143 - OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
0144 range to used for shared memory between Linux and OP-TEE.
0145
0146 The GlobalPlatform TEE Client API [5] is implemented on top of the generic
0147 TEE API.
0148
0149 Picture of the relationship between the different components in the
0150 OP-TEE architecture::
0151
0152 User space Kernel Secure world
0153 ~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
0154 +--------+ +-------------+
0155 | Client | | Trusted |
0156 +--------+ | Application |
0157 /\ +-------------+
0158 || +----------+ /\
0159 || |tee- | ||
0160 || |supplicant| \/
0161 || +----------+ +-------------+
0162 \/ /\ | TEE Internal|
0163 +-------+ || | API |
0164 + TEE | || +--------+--------+ +-------------+
0165 | Client| || | TEE | OP-TEE | | OP-TEE |
0166 | API | \/ | subsys | driver | | Trusted OS |
0167 +-------+----------------+----+-------+----+-----------+-------------+
0168 | Generic TEE API | | OP-TEE MSG |
0169 | IOCTL (TEE_IOC_*) | | SMCCC (OPTEE_SMC_CALL_*) |
0170 +-----------------------------+ +------------------------------+
0171
0172 RPC (Remote Procedure Call) are requests from secure world to kernel driver
0173 or tee-supplicant. An RPC is identified by a special range of SMCCC return
0174 values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
0175 kernel are handled by the kernel driver. Other RPC messages will be forwarded to
0176 tee-supplicant without further involvement of the driver, except switching
0177 shared memory buffer representation.
0178
0179 OP-TEE device enumeration
0180 -------------------------
0181
0182 OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in
0183 order to support device enumeration. In other words, OP-TEE driver invokes this
0184 application to retrieve a list of Trusted Applications which can be registered
0185 as devices on the TEE bus.
0186
0187 OP-TEE notifications
0188 --------------------
0189
0190 There are two kinds of notifications that secure world can use to make
0191 normal world aware of some event.
0192
0193 1. Synchronous notifications delivered with ``OPTEE_RPC_CMD_NOTIFICATION``
0194 using the ``OPTEE_RPC_NOTIFICATION_SEND`` parameter.
0195 2. Asynchronous notifications delivered with a combination of a non-secure
0196 edge-triggered interrupt and a fast call from the non-secure interrupt
0197 handler.
0198
0199 Synchronous notifications are limited by depending on RPC for delivery,
0200 this is only usable when secure world is entered with a yielding call via
0201 ``OPTEE_SMC_CALL_WITH_ARG``. This excludes such notifications from secure
0202 world interrupt handlers.
0203
0204 An asynchronous notification is delivered via a non-secure edge-triggered
0205 interrupt to an interrupt handler registered in the OP-TEE driver. The
0206 actual notification value are retrieved with the fast call
0207 ``OPTEE_SMC_GET_ASYNC_NOTIF_VALUE``. Note that one interrupt can represent
0208 multiple notifications.
0209
0210 One notification value ``OPTEE_SMC_ASYNC_NOTIF_VALUE_DO_BOTTOM_HALF`` has a
0211 special meaning. When this value is received it means that normal world is
0212 supposed to make a yielding call ``OPTEE_MSG_CMD_DO_BOTTOM_HALF``. This
0213 call is done from the thread assisting the interrupt handler. This is a
0214 building block for OP-TEE OS in secure world to implement the top half and
0215 bottom half style of device drivers.
0216
0217 AMD-TEE driver
0218 ==============
0219
0220 The AMD-TEE driver handles the communication with AMD's TEE environment. The
0221 TEE environment is provided by AMD Secure Processor.
0222
0223 The AMD Secure Processor (formerly called Platform Security Processor or PSP)
0224 is a dedicated processor that features ARM TrustZone technology, along with a
0225 software-based Trusted Execution Environment (TEE) designed to enable
0226 third-party Trusted Applications. This feature is currently enabled only for
0227 APUs.
0228
0229 The following picture shows a high level overview of AMD-TEE::
0230
0231 |
0232 x86 |
0233 |
0234 User space (Kernel space) | AMD Secure Processor (PSP)
0235 ~~~~~~~~~~ ~~~~~~~~~~~~~~ | ~~~~~~~~~~~~~~~~~~~~~~~~~~
0236 |
0237 +--------+ | +-------------+
0238 | Client | | | Trusted |
0239 +--------+ | | Application |
0240 /\ | +-------------+
0241 || | /\
0242 || | ||
0243 || | \/
0244 || | +----------+
0245 || | | TEE |
0246 || | | Internal |
0247 \/ | | API |
0248 +---------+ +-----------+---------+ +----------+
0249 | TEE | | TEE | AMD-TEE | | AMD-TEE |
0250 | Client | | subsystem | driver | | Trusted |
0251 | API | | | | | OS |
0252 +---------+-----------+----+------+---------+---------+----------+
0253 | Generic TEE API | | ASP | Mailbox |
0254 | IOCTL (TEE_IOC_*) | | driver | Register Protocol |
0255 +--------------------------+ +---------+--------------------+
0256
0257 At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the
0258 CPU to PSP mailbox register to submit commands to the PSP. The format of the
0259 command buffer is opaque to the ASP driver. It's role is to submit commands to
0260 the secure processor and return results to AMD-TEE driver. The interface
0261 between AMD-TEE driver and AMD Secure Processor driver can be found in [6].
0262
0263 The AMD-TEE driver packages the command buffer payload for processing in TEE.
0264 The command buffer format for the different TEE commands can be found in [7].
0265
0266 The TEE commands supported by AMD-TEE Trusted OS are:
0267
0268 * TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into
0269 TEE environment.
0270 * TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment.
0271 * TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA.
0272 * TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA
0273 * TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA
0274 * TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory
0275 * TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory
0276
0277 AMD-TEE Trusted OS is the firmware running on AMD Secure Processor.
0278
0279 The AMD-TEE driver registers itself with TEE subsystem and implements the
0280 following driver function callbacks:
0281
0282 * get_version - returns the driver implementation id and capability.
0283 * open - sets up the driver context data structure.
0284 * release - frees up driver resources.
0285 * open_session - loads the TA binary and opens session with loaded TA.
0286 * close_session - closes session with loaded TA and unloads it.
0287 * invoke_func - invokes a command with loaded TA.
0288
0289 cancel_req driver callback is not supported by AMD-TEE.
0290
0291 The GlobalPlatform TEE Client API [5] can be used by the user space (client) to
0292 talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening
0293 a session, invoking commands and closing session with TA.
0294
0295 References
0296 ==========
0297
0298 [1] https://github.com/OP-TEE/optee_os
0299
0300 [2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
0301
0302 [3] drivers/tee/optee/optee_smc.h
0303
0304 [4] drivers/tee/optee/optee_msg.h
0305
0306 [5] http://www.globalplatform.org/specificationsdevice.asp look for
0307 "TEE Client API Specification v1.0" and click download.
0308
0309 [6] include/linux/psp-tee.h
0310
0311 [7] drivers/tee/amdtee/amdtee_if.h
