[linux-2.6-block.git] / Documentation / staging / tee.rst

=============
TEE subsystem
=============

This document describes the TEE subsystem in Linux.

A TEE (Trusted Execution Environment) is a trusted OS running in some
secure environment, for example, TrustZone on ARM CPUs, or a separate
secure co-processor etc. A TEE driver handles the details needed to
communicate with the TEE.

This subsystem deals with:

- Registration of TEE drivers

- Managing shared memory between Linux and the TEE

- Providing a generic API to the TEE

The TEE interface
=================

include/uapi/linux/tee.h defines the generic interface to a TEE.

User space (the client) connects to the driver by opening /dev/tee[0-9]* or
/dev/teepriv[0-9]*.

- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor
  which user space can mmap. When user space doesn't need the file
  descriptor any more, it should be closed. When shared memory isn't needed
  any longer it should be unmapped with munmap() to allow the reuse of
  memory.

- TEE_IOC_VERSION lets user space know which TEE this driver handles and
  its capabilities.

- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application.

- TEE_IOC_INVOKE invokes a function in a Trusted Application.

- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE.

- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application.

There are two classes of clients, normal clients and supplicants. The latter is
a helper process for the TEE to access resources in Linux, for example file
system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
/dev/teepriv[0-9].

Much of the communication between clients and the TEE is opaque to the
driver. The main job for the driver is to receive requests from the
clients, forward them to the TEE and send back the results. In the case of
supplicants the communication goes in the other direction, the TEE sends
requests to the supplicant which then sends back the result.

The TEE kernel interface
========================

Kernel provides a TEE bus infrastructure where a Trusted Application is
represented as a device identified via Universally Unique Identifier (UUID) and
client drivers register a table of supported device UUIDs.

TEE bus infrastructure registers following APIs:

match():
  iterates over the client driver UUID table to find a corresponding
  match for device UUID. If a match is found, then this particular device is
  probed via corresponding probe API registered by the client driver. This
  process happens whenever a device or a client driver is registered with TEE
  bus.

uevent():
  notifies user-space (udev) whenever a new device is registered on
  TEE bus for auto-loading of modularized client drivers.

TEE bus device enumeration is specific to underlying TEE implementation, so it
is left open for TEE drivers to provide corresponding implementation.

Then TEE client driver can talk to a matched Trusted Application using APIs
listed in include/linux/tee_drv.h.

TEE client driver example
-------------------------

Suppose a TEE client driver needs to communicate with a Trusted Application
having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration
snippet would look like::

	static const struct tee_client_device_id client_id_table[] = {
		{UUID_INIT(0xac6a4085, 0x0e82, 0x4c33,
			   0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)},
		{}
	};

	MODULE_DEVICE_TABLE(tee, client_id_table);

	static struct tee_client_driver client_driver = {
		.id_table	= client_id_table,
		.driver		= {
			.name		= DRIVER_NAME,
			.bus		= &tee_bus_type,
			.probe		= client_probe,
			.remove		= client_remove,
		},
	};

	static int __init client_init(void)
	{
		return driver_register(&client_driver.driver);
	}

	static void __exit client_exit(void)
	{
		driver_unregister(&client_driver.driver);
	}

	module_init(client_init);
	module_exit(client_exit);

OP-TEE driver
=============

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.

AMD-TEE driver
==============

The AMD-TEE driver handles the communication with AMD's TEE environment. The
TEE environment is provided by AMD Secure Processor.

The AMD Secure Processor (formerly called Platform Security Processor or PSP)
is a dedicated processor that features ARM TrustZone technology, along with a
software-based Trusted Execution Environment (TEE) designed to enable
third-party Trusted Applications. This feature is currently enabled only for
APUs.

The following picture shows a high level overview of AMD-TEE::

                                             |
    x86                                      |
                                             |
 User space            (Kernel space)        |    AMD Secure Processor (PSP)
 ~~~~~~~~~~            ~~~~~~~~~~~~~~        |    ~~~~~~~~~~~~~~~~~~~~~~~~~~
                                             |
 +--------+                                  |       +-------------+
 | Client |                                  |       | Trusted     |
 +--------+                                  |       | Application |
     /\                                      |       +-------------+
     ||                                      |             /\
     ||                                      |             ||
     ||                                      |             \/
     ||                                      |         +----------+
     ||                                      |         |   TEE    |
     ||                                      |         | Internal |
     \/                                      |         |   API    |
 +---------+           +-----------+---------+         +----------+
 | TEE     |           | TEE       | AMD-TEE |         | AMD-TEE  |
 | Client  |           | subsystem | driver  |         | Trusted  |
 | API     |           |           |         |         |   OS     |
 +---------+-----------+----+------+---------+---------+----------+
 |   Generic TEE API        |      | ASP     |      Mailbox       |
 |   IOCTL (TEE_IOC_*)      |      | driver  | Register Protocol  |
 +--------------------------+      +---------+--------------------+

At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the
CPU to PSP mailbox regsister to submit commands to the PSP. The format of the
command buffer is opaque to the ASP driver. It's role is to submit commands to
the secure processor and return results to AMD-TEE driver. The interface
between AMD-TEE driver and AMD Secure Processor driver can be found in [6].

The AMD-TEE driver packages the command buffer payload for processing in TEE.
The command buffer format for the different TEE commands can be found in [7].

The TEE commands supported by AMD-TEE Trusted OS are:

* TEE_CMD_ID_LOAD_TA          - loads a Trusted Application (TA) binary into
                                TEE environment.
* TEE_CMD_ID_UNLOAD_TA        - unloads TA binary from TEE environment.
* TEE_CMD_ID_OPEN_SESSION     - opens a session with a loaded TA.
* TEE_CMD_ID_CLOSE_SESSION    - closes session with loaded TA
* TEE_CMD_ID_INVOKE_CMD       - invokes a command with loaded TA
* TEE_CMD_ID_MAP_SHARED_MEM   - maps shared memory
* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory

AMD-TEE Trusted OS is the firmware running on AMD Secure Processor.

The AMD-TEE driver registers itself with TEE subsystem and implements the
following driver function callbacks:

* get_version - returns the driver implementation id and capability.
* open - sets up the driver context data structure.
* release - frees up driver resources.
* open_session - loads the TA binary and opens session with loaded TA.
* close_session -  closes session with loaded TA and unloads it.
* invoke_func - invokes a command with loaded TA.

cancel_req driver callback is not supported by AMD-TEE.

The GlobalPlatform TEE Client API [5] can be used by the user space (client) to
talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening
a session, invoking commands and clossing session with TA.

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] include/linux/psp-tee.h

[7] drivers/tee/amdtee/amdtee_if.h
Commit	Line	Data
4297739f	1	=============
6a6e7700	2	TEE subsystem
4297739f MCC	3	=============
4297739f MCC	4
6a6e7700 JW	5	This document describes the TEE subsystem in Linux.
	6
	7	A TEE (Trusted Execution Environment) is a trusted OS running in some
	8	secure environment, for example, TrustZone on ARM CPUs, or a separate
	9	secure co-processor etc. A TEE driver handles the details needed to
	10	communicate with the TEE.
	11
	12	This subsystem deals with:
	13
	14	- Registration of TEE drivers
	15
	16	- Managing shared memory between Linux and the TEE
	17
	18	- Providing a generic API to the TEE
	19
	20	The TEE interface
	21	=================
	22
	23	include/uapi/linux/tee.h defines the generic interface to a TEE.
	24
	25	User space (the client) connects to the driver by opening /dev/tee[0-9]* or
	26	/dev/teepriv[0-9]*.
	27
	28	- TEE_IOC_SHM_ALLOC allocates shared memory and returns a file descriptor
	29	which user space can mmap. When user space doesn't need the file
	30	descriptor any more, it should be closed. When shared memory isn't needed
	31	any longer it should be unmapped with munmap() to allow the reuse of
	32	memory.
	33
	34	- TEE_IOC_VERSION lets user space know which TEE this driver handles and
e47cf0c9	35	its capabilities.
6a6e7700 JW	36
	37	- TEE_IOC_OPEN_SESSION opens a new session to a Trusted Application.
	38
	39	- TEE_IOC_INVOKE invokes a function in a Trusted Application.
	40
	41	- TEE_IOC_CANCEL may cancel an ongoing TEE_IOC_OPEN_SESSION or TEE_IOC_INVOKE.
	42
	43	- TEE_IOC_CLOSE_SESSION closes a session to a Trusted Application.
	44
	45	There are two classes of clients, normal clients and supplicants. The latter is
	46	a helper process for the TEE to access resources in Linux, for example file
	47	system access. A normal client opens /dev/tee[0-9]* and a supplicant opens
	48	/dev/teepriv[0-9].
	49
	50	Much of the communication between clients and the TEE is opaque to the
	51	driver. The main job for the driver is to receive requests from the
	52	clients, forward them to the TEE and send back the results. In the case of
	53	supplicants the communication goes in the other direction, the TEE sends
	54	requests to the supplicant which then sends back the result.
	55
2253bd84 SG	56	The TEE kernel interface
	57	========================
	58
	59	Kernel provides a TEE bus infrastructure where a Trusted Application is
	60	represented as a device identified via Universally Unique Identifier (UUID) and
	61	client drivers register a table of supported device UUIDs.
	62
	63	TEE bus infrastructure registers following APIs:
9a32500a DA	64
	65	match():
	66	iterates over the client driver UUID table to find a corresponding
	67	match for device UUID. If a match is found, then this particular device is
	68	probed via corresponding probe API registered by the client driver. This
	69	process happens whenever a device or a client driver is registered with TEE
	70	bus.
	71
	72	uevent():
	73	notifies user-space (udev) whenever a new device is registered on
	74	TEE bus for auto-loading of modularized client drivers.
2253bd84 SG	75
	76	TEE bus device enumeration is specific to underlying TEE implementation, so it
	77	is left open for TEE drivers to provide corresponding implementation.
	78
	79	Then TEE client driver can talk to a matched Trusted Application using APIs
	80	listed in include/linux/tee_drv.h.
	81
	82	TEE client driver example
	83	-------------------------
	84
	85	Suppose a TEE client driver needs to communicate with a Trusted Application
	86	having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration
	87	snippet would look like::
	88
	89	static const struct tee_client_device_id client_id_table[] = {
	90	{UUID_INIT(0xac6a4085, 0x0e82, 0x4c33,
	91	0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)},
	92	{}
	93	};
	94
	95	MODULE_DEVICE_TABLE(tee, client_id_table);
	96
	97	static struct tee_client_driver client_driver = {
	98	.id_table = client_id_table,
	99	.driver = {
	100	.name = DRIVER_NAME,
	101	.bus = &tee_bus_type,
	102	.probe = client_probe,
	103	.remove = client_remove,
	104	},
	105	};
	106
	107	static int __init client_init(void)
	108	{
	109	return driver_register(&client_driver.driver);
	110	}
	111
	112	static void __exit client_exit(void)
	113	{
	114	driver_unregister(&client_driver.driver);
	115	}
	116
	117	module_init(client_init);
	118	module_exit(client_exit);
	119
6a6e7700 JW	120	OP-TEE driver
	121	=============
	122
	123	The OP-TEE driver handles OP-TEE [1] based TEEs. Currently it is only the ARM
	124	TrustZone based OP-TEE solution that is supported.
	125
	126	Lowest level of communication with OP-TEE builds on ARM SMC Calling
	127	Convention (SMCCC) [2], which is the foundation for OP-TEE's SMC interface
	128	[3] used internally by the driver. Stacked on top of that is OP-TEE Message
	129	Protocol [4].
	130
	131	OP-TEE SMC interface provides the basic functions required by SMCCC and some
	132	additional functions specific for OP-TEE. The most interesting functions are:
	133
	134	- OPTEE_SMC_FUNCID_CALLS_UID (part of SMCCC) returns the version information
	135	which is then returned by TEE_IOC_VERSION
	136
	137	- OPTEE_SMC_CALL_GET_OS_UUID returns the particular OP-TEE implementation, used
	138	to tell, for instance, a TrustZone OP-TEE apart from an OP-TEE running on a
	139	separate secure co-processor.
	140
	141	- OPTEE_SMC_CALL_WITH_ARG drives the OP-TEE message protocol
	142
	143	- OPTEE_SMC_GET_SHM_CONFIG lets the driver and OP-TEE agree on which memory
	144	range to used for shared memory between Linux and OP-TEE.
	145
	146	The GlobalPlatform TEE Client API [5] is implemented on top of the generic
	147	TEE API.
	148
	149	Picture of the relationship between the different components in the
4297739f MCC	150	OP-TEE architecture::
	151
	152	User space Kernel Secure world
	153	~~~~~~~~~~ ~~~~~~ ~~~~~~~~~~~~
	154	+--------+ +-------------+
	155	\| Client \| \| Trusted \|
	156	+--------+ \| Application \|
	157	/\ +-------------+
	158	\|\| +----------+ /\
	159	\|\| \|tee- \| \|\|
	160	\|\| \|supplicant\| \/
	161	\|\| +----------+ +-------------+
	162	\/ /\ \| TEE Internal\|
	163	+-------+ \|\| \| API \|
	164	+ TEE \| \|\| +--------+--------+ +-------------+
	165	\| Client\| \|\| \| TEE \| OP-TEE \| \| OP-TEE \|
	166	\| API \| \/ \| subsys \| driver \| \| Trusted OS \|
	167	+-------+----------------+----+-------+----+-----------+-------------+
	168	\| Generic TEE API \| \| OP-TEE MSG \|
	169	\| IOCTL (TEE_IOC_) \| \| SMCCC (OPTEE_SMC_CALL_) \|
	170	+-----------------------------+ +------------------------------+
6a6e7700 JW	171
	172	RPC (Remote Procedure Call) are requests from secure world to kernel driver
	173	or tee-supplicant. An RPC is identified by a special range of SMCCC return
	174	values from OPTEE_SMC_CALL_WITH_ARG. RPC messages which are intended for the
	175	kernel are handled by the kernel driver. Other RPC messages will be forwarded to
	176	tee-supplicant without further involvement of the driver, except switching
	177	shared memory buffer representation.
	178
2253bd84 SG	179	OP-TEE device enumeration
	180	-------------------------
	181
	182	OP-TEE provides a pseudo Trusted Application: drivers/tee/optee/device.c in
	183	order to support device enumeration. In other words, OP-TEE driver invokes this
	184	application to retrieve a list of Trusted Applications which can be registered
	185	as devices on the TEE bus.
	186
79bfa4e7 RT	187	AMD-TEE driver
	188	==============
	189
	190	The AMD-TEE driver handles the communication with AMD's TEE environment. The
	191	TEE environment is provided by AMD Secure Processor.
	192
	193	The AMD Secure Processor (formerly called Platform Security Processor or PSP)
	194	is a dedicated processor that features ARM TrustZone technology, along with a
	195	software-based Trusted Execution Environment (TEE) designed to enable
	196	third-party Trusted Applications. This feature is currently enabled only for
	197	APUs.
	198
	199	The following picture shows a high level overview of AMD-TEE::
	200
	201	\|
	202	x86 \|
	203	\|
	204	User space (Kernel space) \| AMD Secure Processor (PSP)
	205	~~~~~~~~~~ ~~~~~~~~~~~~~~ \| ~~~~~~~~~~~~~~~~~~~~~~~~~~
	206	\|
	207	+--------+ \| +-------------+
	208	\| Client \| \| \| Trusted \|
	209	+--------+ \| \| Application \|
	210	/\ \| +-------------+
	211	\|\| \| /\
	212	\|\| \| \|\|
	213	\|\| \| \/
	214	\|\| \| +----------+
	215	\|\| \| \| TEE \|
	216	\|\| \| \| Internal \|
	217	\/ \| \| API \|
	218	+---------+ +-----------+---------+ +----------+
	219	\| TEE \| \| TEE \| AMD-TEE \| \| AMD-TEE \|
	220	\| Client \| \| subsystem \| driver \| \| Trusted \|
	221	\| API \| \| \| \| \| OS \|
	222	+---------+-----------+----+------+---------+---------+----------+
	223	\| Generic TEE API \| \| ASP \| Mailbox \|
	224	\| IOCTL (TEE_IOC_*) \| \| driver \| Register Protocol \|
	225	+--------------------------+ +---------+--------------------+
	226
	227	At the lowest level (in x86), the AMD Secure Processor (ASP) driver uses the
	228	CPU to PSP mailbox regsister to submit commands to the PSP. The format of the
	229	command buffer is opaque to the ASP driver. It's role is to submit commands to
	230	the secure processor and return results to AMD-TEE driver. The interface
	231	between AMD-TEE driver and AMD Secure Processor driver can be found in [6].
	232
	233	The AMD-TEE driver packages the command buffer payload for processing in TEE.
	234	The command buffer format for the different TEE commands can be found in [7].
	235
	236	The TEE commands supported by AMD-TEE Trusted OS are:
8e2a46a4	237
79bfa4e7 RT	238	* TEE_CMD_ID_LOAD_TA - loads a Trusted Application (TA) binary into
	239	TEE environment.
	240	* TEE_CMD_ID_UNLOAD_TA - unloads TA binary from TEE environment.
	241	* TEE_CMD_ID_OPEN_SESSION - opens a session with a loaded TA.
	242	* TEE_CMD_ID_CLOSE_SESSION - closes session with loaded TA
	243	* TEE_CMD_ID_INVOKE_CMD - invokes a command with loaded TA
	244	* TEE_CMD_ID_MAP_SHARED_MEM - maps shared memory
	245	* TEE_CMD_ID_UNMAP_SHARED_MEM - unmaps shared memory
	246
	247	AMD-TEE Trusted OS is the firmware running on AMD Secure Processor.
	248
	249	The AMD-TEE driver registers itself with TEE subsystem and implements the
	250	following driver function callbacks:
	251
	252	* get_version - returns the driver implementation id and capability.
	253	* open - sets up the driver context data structure.
	254	* release - frees up driver resources.
	255	* open_session - loads the TA binary and opens session with loaded TA.
	256	* close_session - closes session with loaded TA and unloads it.
	257	* invoke_func - invokes a command with loaded TA.
	258
	259	cancel_req driver callback is not supported by AMD-TEE.
	260
	261	The GlobalPlatform TEE Client API [5] can be used by the user space (client) to
	262	talk to AMD's TEE. AMD's TEE provides a secure environment for loading, opening
	263	a session, invoking commands and clossing session with TA.
	264
4297739f MCC	265	References
	266	==========
	267
6a6e7700	268	[1] https://github.com/OP-TEE/optee_os
4297739f	269
6a6e7700	270	[2] http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html
4297739f	271
6a6e7700	272	[3] drivers/tee/optee/optee_smc.h
4297739f	273
6a6e7700	274	[4] drivers/tee/optee/optee_msg.h
4297739f	275
6a6e7700 JW	276	[5] http://www.globalplatform.org/specificationsdevice.asp look for
6a6e7700 JW	277	"TEE Client API Specification v1.0" and click download.
79bfa4e7 RT	278
	279	[6] include/linux/psp-tee.h
	280
	281	[7] drivers/tee/amdtee/amdtee_if.h