diff options
49 files changed, 4 insertions, 4400 deletions
diff --git a/Notice.md b/Notice.md deleted file mode 100644 index f8db98f8..00000000 --- a/Notice.md +++ /dev/null @@ -1,157 +0,0 @@ -OP-TEE -======= - -This is the repository of OP-TEE (Open Portable Trusted Execution Environment), -the open-source TEE maintained by Linaro, with initial contributions from -STMicroelectronics, Ericsson and Linaro Limited. - -What OP-TEE is -------- - -OP-TEE is a Trusted Execution Environment designed as companion to a non-secure -Linux kernel running on ARM® Cortex-A cores using the TrustZone® -technology. OP-TEE meets the TEE System Architecture and provides the TEE -Internal Core API v1.1 to Trusted Applications and the TEE Client API -v1.0, all as defined by the [GlobalPlatform TEE specifications]. - -The non-secure OS is referred to as the Rich Execution Environment (REE) in TEE -specifications. It is typically a Linux OS flavor as a GNU/Linux distribution -or the AOSP. - -OP-TEE is designed primarily to rely on the ARM TrustZone technology as -the underlying hardware isolation mechanism. However, it has been structured -to be compatible with any isolation technology suitable for the TEE concept and -goals, such as running as a virtual machine or on a dedicated CPU. - -The main design goals for OP-TEE are: -- Isolation - the TEE provides isolation from the non-secure OS and - protects the loaded Trusted Applications (TAs) from each other using - underlying HW support, -- Small footprint - the TEE should remain small enough to - reside in a reasonable amount of on-chip memory as found on ARM - based systems, -- Portability - the TEE aims at being easily pluggable to different - architectures and available HW and has to support various setups - such as multiple client OSes or multiple TEEs. - - -Repository structure ------- - -OP-TEE comes with several components: -- a secure privileged layer, executing at ARM secure PL-1 level, -- a set of secure userland libraries designed for Trusted Applications - needs, -- a Linux kernel driver merged since v4.12, -- a Linux userland library designed upon the GPD TEE Client API - specifications -- a Linux userland supplicant application for remote services expected by - the TEE OS, -- and some build scripts, debugging tools and examples to ease its - integration and the development of trusted applications and secure - services. - -These components are available from several git repositories. The main ones are -the [optee_os], the [optee_client] and the [Linux kernel] since v4.12. - -The [optee_os] git repository contains the source code for the TEE OS itself. -It includes the secure privileged layer hosting the Trusted Applications and -libraries complying with the TEE Internal Core API v1.1. It is distributed mostly -under the [BSD 2-Clause] open-source license. It includes few external files under -[BSD 3-Clause] license or other free software licenses. - -The [optee_client] git repository contains the source code for the TEE client -library in a Linux OS providing the TEE Client API v1.0. It is distributed under -the [BSD 2-Clause] open-source license. - -The [Linux kernel] contains the source code for the OP-TEE Linux driver. It is -distributed under the [GPLv2] open-source license. - -There are other OP-TEE components one might be interested in. The OP-TEE release tag -references several git repositories enabling OP-TEE build and test for various -platforms. Refer to the [build documentation] for information. The [optee_test] git -repository proposes test materials through the `xtest` tool and dedicated trusted -applications. The [optee_examples] git repository contains examples of TEE client -and trusted applications and some documentation to get hands on trusted -application development. - -Documentation ------- -Documentation on design, implementation and tools can be found in -[optee_os/documentation](optee_os/documentation). - -Contributions ------- - -Contributions to OP-TEE are managed by the OP-TEE gatekeepers, whose contact -email is op-tee[at]linaro[.]org. - -Anyone can contribute to OP-TEE as long as it is understood that it will require -a sign-off. The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch (see below). You thereby assure that you have -read and are following the rules stated in the `Developer Certificate of Origin` -as stated below. - -``` -Developer Certificate of Origin -Version 1.1 - -Copyright (C) 2004, 2006 The Linux Foundation and its contributors. -660 York Street, Suite 102, -San Francisco, CA 94110 USA - -Everyone is permitted to copy and distribute verbatim copies of this -license document, but changing it is not allowed. - - -Developer's Certificate of Origin 1.1 - -By making a contribution to this project, I certify that: - -(a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - -(b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - -(c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - -(d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. -``` - -We have borrowed this procedure from the Linux kernel project to -improve tracking of who did what, and for legal reasons. - -To sign-off a patch, just add a line saying: -``` - Signed-off-by: Random J Developer <random@developer.example.org> -``` -using your real name (sorry, no pseudonyms or anonymous contributions.) - -Refer also to [github.md](documentation/github.md) to setup a github accournt -in order to contribute to the project through issues reporting and pull -requests. - -[BSD 2-Clause]: http://opensource.org/licenses/BSD-2-Clause -[BSD 3-Clause]: http://opensource.org/licenses/BSD-3-Clause -[GPLv2]: https://opensource.org/licenses/gpl-2.0 -[build documentation]: documentation/build_system.md -[GlobalPlatform TEE specifications]: https://www.globalplatform.org/specificationsdevice.asp -[Linux kernel]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git -[optee_client]: https://github.com/OP-TEE/optee_client -[optee_examples]: https://github.com/OP-TEE/optee_examples -[optee_os]: https://github.com/OP-TEE/optee_os -[optee_test]: https://github.com/OP-TEE/optee_test @@ -1,147 +1,7 @@ # OP-TEE Trusted OS -## Contents -1. [Introduction](#1-introduction) -2. [License](#2-license) -3. [Platforms supported](#3-platforms-supported) -4. [Get and build OP-TEE software](#4-get-and-build-op-tee-software) -5. [Coding standards](#5-coding-standards) +This git contains source code for the secure side implementation of OP-TEE +project. -## 1. Introduction -The `optee_os` git repository contains the source code of a Trusted Execution -Environment (TEE) as companion to a non-secure OS on ARM® -Cortex-A cores using the TrustZone® technology. This component meets the -[TEE System Architecture specifications](http://www.globalplatform.org/specificationsdevice.asp) -and provides the -[TEE Internal Core API v1.1](http://www.globalplatform.org/specificationsdevice.asp) -as defined by the -[GlobalPlatform Device technology TEE specifications](http://www.globalplatform.org/specificationsdevice.asp) -for the development of -Trusted Applications. For a general overview of OP-TEE and to find out how to -contribute, please see the [Notice.md](Notice.md) file. +All official OP-TEE documentation has moved to http://optee.readthedocs.io. -The Trusted OS is accessible from the Rich OS (Linux) using the -[GlobalPlatform TEE Client API Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp), -which also is used to trigger secure execution of applications within the TEE. - ---- -## 2. License -The software is distributed mostly under the -[BSD 2-Clause](http://opensource.org/licenses/BSD-2-Clause) open source -license, apart from some files in the `optee_os/lib/libutils` directory -which are distributed under the -[BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause) or public domain -licenses. - ---- -## 3. Platforms supported -Several platforms are supported. In order to manage slight differences -between platforms, a `PLATFORM_FLAVOR` flag has been introduced. -The `PLATFORM` and `PLATFORM_FLAVOR` flags define the whole configuration -for a chip the where the Trusted OS runs. Note that there is also a -composite form which makes it possible to append `PLATFORM_FLAVOR` directly, -by adding a dash in-between the names. The composite form is shown below -for the different boards. For more specific details about build flags etc, -please read the file [build_system.md](documentation/build_system.md). Some -platforms have different sub-maintainers, please refer to the file -[MAINTAINERS](MAINTAINERS) for contact details for various platforms. - -The **Maintained?** column shows: - -- A green image if the platform is actively maintained: either tested successfully - with the latest release (N), or is a newly supported platform. -- An orange image if the platform was last tested successfully with release N-1. -- A red image if the last successful test report is older. - -<!-- Please keep this list sorted in alphabetic order --> -| Platform | Composite PLATFORM flag | Publicly available? | Maintained? | -|----------|-------------------------|---------------------|-------------| -| [ARM Juno Board](http://www.arm.com/products/tools/development-boards/versatile-express/juno-arm-development-platform.php) |`PLATFORM=vexpress-juno`| Yes |  | -| [Atmel ATSAMA5D2-XULT Board](http://www.atmel.com/tools/atsama5d2-xult.aspx)|`PLATFORM=sam`| Yes |  | -| [Broadcom ns3](https://www.broadcom.com/)|`PLATFORM=bcm-ns3`| No |  | -| [DeveloperBox (Socionext Synquacer SC2A11)](https://www.96boards.org/product/developerbox/)|`PLATFORM=synquacer`| Yes |  | -| [FSL ls1021a](http://www.freescale.com/tools/embedded-software-and-tools/hardware-development-tools/tower-development-boards/mcu-and-processor-modules/powerquicc-and-qoriq-modules/qoriq-ls1021a-tower-system-module:TWR-LS1021A?lang_cd=en)|`PLATFORM=ls-ls1021atwr`| Yes |  | -| [NXP ls1043ardb](http://www.nxp.com/products/microcontrollers-and-processors/power-architecture-processors/qoriq-platforms/developer-resources/qoriq-ls1043a-reference-design-board:LS1043A-RDB)|`PLATFORM=ls-ls1043ardb`| Yes |  | -| [NXP ls1046ardb](http://www.nxp.com/products/microcontrollers-and-processors/power-architecture-processors/qoriq-platforms/developer-resources/qoriq-ls1046a-reference-design-board:LS1046A-RDB)|`PLATFORM=ls-ls1046ardb`| Yes |  | -| [NXP ls1012ardb](http://www.nxp.com/products/microcontrollers-and-processors/power-architecture-processors/qoriq-platforms/developer-resources/qoriq-ls1012a-reference-design-board:LS1012A-RDB)|`PLATFORM=ls-ls1012ardb`| Yes |  | -| [NXP ls1088ardb](http://www.nxp.com/products/microcontrollers-and-processors/power-architecture-processors/qoriq-platforms/developer-resources/qoriq-ls1088a-reference-design-board:LS1088A-RDB)|`PLATFORM=ls-ls1088ardb`| Yes |  | -| [NXP ls2088ardb](http://www.nxp.com/products/microcontrollers-and-processors/power-architecture-processors/qoriq-platforms/developer-resources/qoriq-ls2088a-reference-design-board:LS2088A-RDB)|`PLATFORM=ls-ls2088ardb`| Yes |  | -| [NXP ls1012afrwy](https://www.nxp.com/support/developer-resources/software-development-tools/qoriq-developer-resources/layerscape-frwy-ls1012a-board:FRWY-LS1012A)|`PLATFORM=ls-ls1012afrwy`| Yes |  | -| [NXP lx2160ardb](https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/qoriq-layerscape-arm-processors/layerscape-lx2160a-multicore-communications-processor:LX2160A)|`PLATFORM=ls-lx2160ardb`| Yes |  | -| [FSL i.MX6 Quad SABRE Lite Board](https://boundarydevices.com/product/sabre-lite-imx6-sbc/) |`PLATFORM=imx-mx6qsabrelite`| Yes |  | -| [FSL i.MX6 Quad SABRE SD Board](http://www.nxp.com/products/software-and-tools/hardware-development-tools/sabre-development-system/sabre-board-for-smart-devices-based-on-the-i.mx-6quad-applications-processors:RD-IMX6Q-SABRE) |`PLATFORM=imx-mx6qsabresd`| Yes |  | -| [SolidRun i.MX6 Quad Hummingboard Edge](https://www.solid-run.com/product/hummingboard-edge-imx6q-wa-h/) |`PLATFORM=imx-mx6qhmbedge`| Yes |  | -| [SolidRun i.MX6 Dual Hummingboard Edge](https://www.solid-run.com/product/hummingboard-edge-imx6d-wa-h/) |`PLATFORM=imx-mx6dhmbedge`| Yes |  | -| [SolidRun i.MX6 Dual Lite Hummingboard Edge](https://www.solid-run.com/product/hummingboard-edge-imx6dl-0c-h/) |`PLATFORM=imx-mx6dlhmbedge`| Yes |  | -| [SolidRun i.MX6 Solo Hummingboard Edge](https://www.solid-run.com/product/hummingboard-edge-imx6s-wa-h/) |`PLATFORM=imx-mx6shmbedge`| Yes |  | -| [FSL i.MX6 UltraLite EVK Board](http://www.freescale.com/products/arm-processors/i.mx-applications-processors-based-on-arm-cores/i.mx-6-processors/i.mx6qp/i.mx6ultralite-evaluation-kit:MCIMX6UL-EVK) |`PLATFORM=imx-mx6ulevk`| Yes |  | -| [NXP i.MX7Dual SabreSD Board](http://www.nxp.com/products/software-and-tools/hardware-development-tools/sabre-development-system/sabre-board-for-smart-devices-based-on-the-i.mx-7dual-applications-processors:MCIMX7SABRE) |`PLATFORM=imx-mx7dsabresd`| Yes |  | -| [NXP i.MX7Solo WaRP7 Board](http://www.nxp.com/products/developer-resources/reference-designs/warp7-next-generation-iot-and-wearable-development-platform:WARP7) |`PLATFORM=imx-mx7swarp7`| Yes |  | -| [NXP i.MX7Solo WaRP7 Board - Mbed Linux OS](https://os.mbed.com/platforms/WaRP7) |`PLATFORM=imx-mx7swarp7_mbl`| Yes |  | -| [NXP i.MX8MQEVK Board](https://www.nxp.com/support/developer-resources/run-time-software/i.mx-developer-resources/evaluation-kit-for-the-i.mx-8m-applications-processor:MCIMX8M-EVK) |`PLATFORM=imx-imx8mqevk`| Yes |  | -| [NXP i.MX8MMEVK Board](https://www.nxp.com/products/processors-and-microcontrollers/arm-based-processors-and-mcus/i.mx-applications-processors/i.mx-8-processors/i.mx-8m-mini-family-arm-cortex-a53-cortex-m4-audio-voice-video:i.MX8MMINI?lang=en&lang_cd=en&) |`PLATFORM=imx-imx8mmevk`| Yes |  | -| [ARM Foundation FVP](https://developer.arm.com/products/system-design/fixed-virtual-platforms) |`PLATFORM=vexpress-fvp`| Yes |  | -| [HiSilicon D02](http://open-estuary.org/d02-2)|`PLATFORM=d02`| No |  | -| [HiKey Board (HiSilicon Kirin 620)](https://www.96boards.org/product/hikey)|`PLATFORM=hikey` or `PLATFORM=hikey-hikey`| Yes |  | -| [HiKey960 Board (HiSilicon Kirin 960)](https://www.96boards.org/product/hikey960)|`PLATFORM=hikey-hikey960`| Yes |  | -| [Marvell ARMADA 7K Family](http://www.marvell.com/embedded-processors/armada-70xx/)|`PLATFORM=marvell-armada7k8k`| Yes |  | -| [Marvell ARMADA 8K Family](http://www.marvell.com/embedded-processors/armada-80xx/)|`PLATFORM=marvell-armada7k8k`| Yes |  | -| [Marvell ARMADA 3700 Family](http://www.marvell.com/embedded-processors/armada-3700/)|`PLATFORM=marvell-armada3700`| Yes |  | -| [MediaTek MT8173 EVB Board](https://www.mediatek.com/products/tablets/mt8173)|`PLATFORM=mediatek-mt8173`| No |  v3.0.0 | -| [Poplar Board (HiSilicon Hi3798C V200)](https://www.96boards.org/product/poplar)|`PLATFORM=poplar`| Yes |  | -| [QEMU](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_virt`| Yes |  | -| [QEMUv8](http://wiki.qemu.org/Main_Page) |`PLATFORM=vexpress-qemu_armv8a`| Yes |  | -| [Raspberry Pi 3](https://www.raspberrypi.org/products/raspberry-pi-3-model-b) |`PLATFORM=rpi3`| Yes |  | -| [Renesas RCAR](https://www.renesas.com/en-sg/solutions/automotive/products/rcar-h3.html)|`PLATFORM=rcar`| No |  | -| [Rockchip RK322X](http://www.rock-chips.com/a/en/products/RK32_Series/2016/1109/799.html) |`PLATFORM=rockchip-rk322x`| No |  | -| [STMicroelectronics b2260 - h410 (96boards fmt)](http://www.st.com/web/en/catalog/mmc/FM131/SC999/SS1628/PF258776) |`PLATFORM=stm-b2260`| No |  | -| [STMicroelectronics b2120 - h310 / h410](http://www.st.com/web/en/catalog/mmc/FM131/SC999/SS1628/PF258776) |`PLATFORM=stm-cannes`| No |  | -| STMicroelectronics stm32mp1 |`PLATFORM=stm32mp1`| No |  | -| [Allwinner A64 Pine64 Board](https://www.pine64.org/) |`PLATFORM=sunxi-sun50i_a64`| Yes |  | -| [Texas Instruments AM65x](http://www.ti.com/lit/ug/spruid7/spruid7.pdf)|`PLATFORM=k3-am65x`| Yes |  | -| [Texas Instruments DRA7xx](http://www.ti.com/processors/automotive-processors/drax-infotainment-socs/overview.html)|`PLATFORM=ti-dra7xx`| Yes |  | -| [Texas Instruments AM57xx](http://www.ti.com/processors/sitara/arm-cortex-a15/am57x/overview.html)|`PLATFORM=ti-am57xx`| Yes |  | -| [Texas Instruments AM43xx](http://www.ti.com/processors/sitara/arm-cortex-a9/am438x/overview.html)|`PLATFORM=ti-am43xx`| Yes |  | -| [Xilinx Zynq 7000 ZC702](http://www.xilinx.com/products/boards-and-kits/ek-z7-zc702-g.html)|`PLATFORM=zynq7k-zc702`| Yes |  v2.3.0 | -| [Xilinx Zynq UltraScale+ MPSOC](http://www.xilinx.com/products/silicon-devices/soc/zynq-ultrascale-mpsoc.html)|`PLATFORM=zynqmp-zcu102`| Yes |  v2.4.0 | -| [Spreadtrum SC9860](http://www.spreadtrum.com/en/SC9860GV.html)|`PLATFORM=sprd-sc9860`| No |  v2.1.0 | - ---- -## 4. Get and build OP-TEE software -Please see [build] for instructions how to run OP-TEE on various devices. - ---- -## 5. Coding standards -In this project we are trying to adhere to the same coding convention as used in -the Linux kernel (see [CodingStyle]). We achieve this by running [checkpatch] -from Linux kernel. However there are a few exceptions that we had to make since -the code also follows GlobalPlatform standards. The exceptions are as follows: - -- CamelCase for GlobalPlatform types are allowed. -- And we also exclude checking third party code that we might use in this - project, such as LibTomCrypt, MPA, newlib (not in this particular git, but - those are also part of the complete TEE solution, see - [Notice.md](Notice.md#repository-structure). The reason for - excluding and not fixing third party code is because we would probably - deviate too much from upstream and therefore it would be hard to rebase - against those projects later on and we don't expect that it is easy to - convince other software projects to change coding style. - Automatic variables should always be initialized. Mixed declarations - and statements are allowed, and may be used to avoid assigning useless - values. Please leave one blank line before and after such declarations. - -Regarding the checkpatch tool, it is not included directly into this project. -Please use checkpatch.pl from the Linux kernel git in combination with the -local [checkpatch script]. - -There are also targets for common use cases in the [Makefile](Makefile): - -``` -make checkpatch #check staging and working area -make checkpatch-staging #check staging area (added, but not committed files) -make checkpatch-working #check working area (modified, but not added files) -``` - -[build]: https://github.com/OP-TEE/build -[checkpatch script]: scripts/checkpatch.sh -[checkpatch]: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/checkpatch.pl -[CodingStyle]: https://www.kernel.org/doc/Documentation/process/coding-style.rst +// OP-TEE core maintainers diff --git a/documentation/abort_dumps.rst b/documentation/abort_dumps.rst deleted file mode 100644 index 619656a6..00000000 --- a/documentation/abort_dumps.rst +++ /dev/null @@ -1,109 +0,0 @@ -When OP-TEE encounters a serious error condition, it prints diagnostic -information to the secure console. The message contains a call stack if -``CFG_UNWIND=y`` (enabled by default). - -The following errors will trigger a dump: - - - Data or prefetch abort exception in the TEE core (kernel mode) or in a TA - (user mode), - - When a user-mode Trusted Application panics, either by calling - ``TEE_Panic()`` directly or due to some error detected by the TEE Core - Internal API, - - When the TEE core detects a fatal error and decides to hang the system - because there is no way to proceed safely (core panic). - -The messages look slightly different depending on: - - - Whether the error is an exception or a panic, - - The exception/privilege level when the exception occurred (PL0/EL0 if a - user mode Trusted Application was running, PL1/EL1 if it was the TEE core), - - Whether the TEE and TA are 32 or 64 bits, - - The exact type of exception (data or prefetch abort, translation fault, - read or write permission fault, alignment errors etc). - -Here is an example of a panic in a 32-bit Trusted Application, running on a -32-bit TEE core (QEMU):: - - E/TC:0 TA panicked with code 0x0 - E/TC:0 Status of TA 484d4143-2d53-4841-3120-4a6f636b6542 (0xe07ba50) (active) - E/TC:0 arch: arm load address: 0x101000 ctx-idr: 1 - E/TC:0 stack: 0x100000 4096 - E/TC:0 region 0: va 0x100000 pa 0xe31d000 size 0x1000 flags rw- - E/TC:0 region 1: va 0x101000 pa 0xe300000 size 0xf000 flags r-x - E/TC:0 region 2: va 0x110000 pa 0xe30f000 size 0x3000 flags r-- - E/TC:0 region 3: va 0x113000 pa 0xe312000 size 0xb000 flags rw- - E/TC:0 region 4: va 0 pa 0 size 0 flags --- - E/TC:0 region 5: va 0 pa 0 size 0 flags --- - E/TC:0 region 6: va 0 pa 0 size 0 flags --- - E/TC:0 region 7: va 0 pa 0 size 0 flags --- - E/TC:0 Call stack: - E/TC:0 0x001044a8 - E/TC:0 0x0010ba59 - E/TC:0 0x00101093 - E/TC:0 0x001013ed - E/TC:0 0x00101545 - E/TC:0 0x0010441b - E/TC:0 0x00104477 - D/TC:0 user_ta_enter:452 tee_user_ta_enter: TA panicked with code 0x0 - D/TC:0 tee_ta_invoke_command:649 Error: ffff3024 of 3 - D/TC:0 tee_ta_close_session:402 tee_ta_close_session(0xe07be98) - D/TC:0 tee_ta_close_session:421 Destroy session - D/TC:0 tee_ta_close_session:447 Destroy TA ctx - - -The above dump was triggered by the TA when entering an irrecoverable error -ending up in a ``TEE_Panic(0)`` call. - -OP-TEE provides a helper script called ``symbolize.py`` to facilitate the -analysis of such issues. It is located in the OP-TEE OS source tree in -``scripts/symbolize.py`` and is also copied to the TA development kit. -Whenever you are confronted with an error message reporting a serious error and -containing a ``"Call stack:"`` line, you may use the symbolize script. - -``symbolize.py`` reads its input from ``stdin`` and writes extended debug -information to ``stdout``. The ``-d`` (directories) option tells the script -where to look for TA ELF file(s) (``<uuid>.stripped.elf``) or for ``tee.elf`` -(the TEE core). Please refer to ``symbolize.py --help`` for details. - -Typical output:: - - $ cat dump.txt | ./optee_os/scripts/symbolize.py -d ./optee_examples/*/ta - # (or run the script, copy and paste the dump, then press Ctrl+D) - E/TC:0 TA panicked with code 0x0 - E/TC:0 Status of TA 484d4143-2d53-4841-3120-4a6f636b6542 (0xe07ba50) (active) - E/TC:0 arch: arm load address: 0x101000 ctx-idr: 1 - E/TC:0 stack: 0x100000 4096 - E/TC:0 region 0: va 0x100000 pa 0xe31d000 size 0x1000 flags rw- - E/TC:0 region 1: va 0x101000 pa 0xe300000 size 0xf000 flags r-x .ta_head .text .rodata - E/TC:0 region 2: va 0x110000 pa 0xe30f000 size 0x3000 flags r-- .rodata .ARM.extab .ARM.extab.text.utee_panic .ARM.extab.text.__aeabi_ldivmod .ARM.extab.text.__aeabi_uldivmod .ARM.exidx .got .dynsym .rel.got .dynamic .dynstr .hash .rel.dyn - E/TC:0 region 3: va 0x113000 pa 0xe312000 size 0xb000 flags rw- .data .bss - E/TC:0 region 4: va 0 pa 0 size 0 flags --- - E/TC:0 region 5: va 0 pa 0 size 0 flags --- - E/TC:0 region 6: va 0 pa 0 size 0 flags --- - E/TC:0 region 7: va 0 pa 0 size 0 flags --- - E/TC:0 Call stack: - E/TC:0 0x001044a8 utee_panic at optee_os/lib/libutee/arch/arm/utee_syscalls_a32.S:74 - E/TC:0 0x0010ba59 TEE_Panic at optee_os/lib/libutee/tee_api_panic.c:35 - E/TC:0 0x00101093 hmac_sha1 at optee_examples/hotp/ta/hotp_ta.c:63 - E/TC:0 0x001013ed get_hotp at optee_examples/hotp/ta/hotp_ta.c:171 - E/TC:0 0x00101545 TA_InvokeCommandEntryPoint at optee_examples/hotp/ta/hotp_ta.c:225 - E/TC:0 0x0010441b entry_invoke_command at optee_os/lib/libutee/arch/arm/user_ta_entry.c:207 - E/TC:0 0x00104477 __utee_entry at optee_os/lib/libutee/arch/arm/user_ta_entry.c:235 - D/TC:0 user_ta_enter:452 tee_user_ta_enter: TA panicked with code 0x0 ??? - D/TC:0 tee_ta_invoke_command:649 Error: ffff3024 of 3 - D/TC:0 tee_ta_close_session:402 tee_ta_close_session(0xe07be98) - D/TC:0 tee_ta_close_session:421 Destroy session - D/TC:0 tee_ta_close_session:447 Destroy TA ctx - -The Python script uses several tools from the GNU Binutils package to perform -the following tasks: - - 1. Translate the call stack addresses into function names, file names and line - numbers. - 2. Convert the abort address to a symbol plus some offset and/or an ELF section - name plus some offset. - 3. Print the names of the ELF sections contained in each memory region of a TA. - -Note that to successfully run ``symbolize.py`` you must also make your toolchain -visible on the ``PATH`` (i.e., ``export PATH=<my-toolchain-path>/bin:$PATH``). - diff --git a/documentation/benchmark.md b/documentation/benchmark.md deleted file mode 100644 index c0d5bf94..00000000 --- a/documentation/benchmark.md +++ /dev/null @@ -1,130 +0,0 @@ -# Benchmark framework -## Contents -1. [Introduction](#1-introduction) -2. [Implementation details](#2-implementation-details) - * [Design overview](#21-design-overview) - * [Timestamp source](#22-timestamp-source) - * [Call sequence diagram](#23-call-sequence-diagram) -3. [Running benchmarks](#3-running-benchmarks) - * [Benchmark application usage](#31-benchmark-application-usage) - * [Adding custom timestamps](#32-adding-custom-timestamps) - * [Analyzing results](#33-analyzing-results) -4. [Limitations and further steps](#4-limitations-and-further-steps) - - -## 1. Introduction -Due to its nature, OP-TEE is being a solution spanning over several -architectural layers, where each layer includes its own complex parts. -For further optimizations of performance, there is a need of tool which will -provide detailed and precise profiling information for each layer. - -It is necessary to receive latency values for: -* The roundtrip time for going from a client application in normal world, -down to a Trusted Application and back again. -* Detailed information for amount of time taken to go through each layer: - * libTEEC -> Linux OP-TEE kernel driver - * Linux OP-TEE kernel driver -> OP-TEE OS Core - * OP-TEE OS Core -> TA entry point (**not supported yet**) - * The same way back ---- -## 2. Implementation details -### 2.1 Design overview - -Benchmark framework consists of such components: -1. **Benchmark CA**: a dedicated client application, which is responsible -for allocating timestamp circular buffers, registering these buffers in -the **Benchmark PTA** and consuming all timestamp data generated -by all OP-TEE layers. Finally, it puts timestamp data into appropriate -file with `.ts` extension. Additional details can be found here -here [optee_benchmark] -2. **Benchmark PTA**: pseudo TA, which owns all per-cpu circular non-secure -buffers from a shared memory. **Benchmark PTA** must be invoked (by a CA) -to register the timestamp circular buffers. In turn, the **Benchmark PTA** -invokes the optee linux driver (through some RPC mean) to register this -circular buffers in the linux kernel layer. -3. **libTEEC** and **Linux OP-TEE kernel driver** include functionality for -handling timestamp buffer registration requests from the **Benchmark PTA**. - -When benchmark is enabled, all OP-TEE layers (**libTEEC**, -**Linux OP-TEE kernel driver**, **OP-TEE OS Core**) do fill the registered -timestamp circular buffer with timestamp data for all invocation requests on -condition that the circular buffer is allocated/registered. - -![design_overview][design_overview] - -### 2.2 Timestamp source - -ARM Performance Monitor Units are used as the main source of timestamp values. -The reason why this technology was chosen is that it is supported on all -ARMv7/ARMv8 cores. Besides it can provide precise pre-cpu cycle counter values, -it is possible to enable EL0 access to all events, so usermode applications -can directly read cpu counter values from coprocessor registers, -achieving minimal latency by avoiding additional syscalls to EL1 core. - -Besides CPU cycle counter values, timestamp by itself contains also -information about: -* Executing CPU core index -* OP-TEE layer id, where this timestamp was -obtained from -* Program counter value when timestamp was logged, which can be used for -getting a symbol name (a filename and line number) - -### 2.3 Call sequence diagram - -![call_sequence][call_sequence] - ---- -## 3 Running benchmarks -### 3.1 Benchmark application usage -Before using Benchmark framework, OP-TEE should be rebuild with -`CFG_TEE_BENCHMARK` flag enabled. -``` -$ make all CFG_TEE_BENCHMARK=y -j4 -``` - -Then, regular CA and its params should be by-passed to optee_benchmark CA. -``` -# benchmark client_app [client_app params] -``` - -When client_app finishes its execution, optee_benchmark will generate -`<client_app>.ts` timestamp data file in the same directory, where CA is -stored. - -### 3.2 Adding custom timestamps -Currently, timestamping is done only for `InvokeCommand` calls, but it's also -possible to choose custom places in the supported OP-TEE layers. - -To add timestamp storing command to custom c source file: -1. Include appropriate header: - * OP-TEE OS Core: `bench.h` - * Linux OP-TEE kmod: `optee_bench.h` - * libTEEC: `teec_benchmark.h` -2. Invoke `bm_timestamp()` (for linux kmod use `optee_bm_timestamp()`) -in the function, where you want to put timestamp from. - -### 3.3 Analyzing results -Will be added soon - ---- -## 4. Limitations and further steps -* Implementation of application which will analyze timestamp data and provide -statistics for different types of calls providing avg/min/max values (both CPU -cycles and time values) -* Add support for all platforms, where OP-TEE is supported -* Adding support of S-EL0 timestamping -* Attaching additional payload information to each timestamp, for example, -session -* Timestamping within interrupt context in the OP-TEE OS Core - -<!-- -To edit benchmark_design diagram use http://draw.io and -benchmark_design.xml source file - -For benchmark call sequence diagram use http://mscgen.js.org and -benchmark_sequence.msc source file ---> - -[design_overview]: images/benchmark/benchmark_design.png -[call_sequence]: images/benchmark/benchmark_sequence.png -[optee_benchmark]: https://github.com/linaro-swg/optee_benchmark diff --git a/documentation/build_system.md b/documentation/build_system.md deleted file mode 100644 index ad2ffba4..00000000 --- a/documentation/build_system.md +++ /dev/null @@ -1,331 +0,0 @@ -# Build system - -The OP-TEE build system is based on GNU make. It consists of a main `Makefile` -in the root of the project together with `sub.mk` files in all source -directories. In addition, some supporting files are used to recursively process -all `sub.mk` files and generate the build rules. - -Name | Description -:-----------------|:----------- -`core/core.mk` | Included from `Makefile` to build the TEE Core -`ta/ta.mk` | Included from `Makefile` to create the TA devkit -`mk/compile.mk` | Create rules to make objects from source files -`mk/lib.mk` | Create rules to make a libraries (.a) -`mk/subdir.mk` | Process `sub.mk` files recursively -`mk/config.mk` | Global configuration variable -`core/arch/$(ARCH)/$(ARCH).mk` | Arch-specific compiler flags -`core/arch/$(ARCH)/plat-$(PLATFORM)/conf.mk` | Platform-specific compiler flags and configuration variables -`core/arch/$(ARCH)/plat-$(PLATFORM)/link.mk` | Make recipes to link the TEE Core -`ta/arch/arm/link.mk` | Make recipes to link Trusted Applications -`ta/mk/ta_dev_kit.mk` | Main Makefile to be included when building Trusted Applications -`mk/checkconf.mk` | Utility functions to manipulate configuration variables and generate a C header file -`sub.mk` | List source files and define compiler flags - -`make` is always invoked from the top-level directory; there is no recursive -invocation of make itself. - -## Choosing the build target - -The target architecture, platform and build directory may be selected by setting -environment or make variables (**VAR=value make** or **make VAR=value**). - -### ARCH (CPU architecture) - -**$(ARCH)** is the CPU architecture to be built. Currently, the only supported -value is **arm** for 32-bit or 64-bit Armv7-A or Armv8-A. Please note that -contrary to the Linux kernel, **$(ARCH)** should **not** be set to **arm64** for -64-bit builds. The **ARCH** variable does not need to be set explicitly before -building either, because the proper instruction set is selected from the -**$(PLATFORM)** value. For platforms that support both 32-bit and 64-bit -builds, **CFG_ARM64_core=y** should be set to select 64-bit and not set (or set -to **n**) to select 32-bit. - -Architecture-specific source code belongs to sub-directories that follow the -`arch/$(ARCH)` pattern, such as: -`core/arch/arm`, `lib/libmpa/arch/arm`, `lib/libutee/arch/arm` and -so on. - -### PLATFORM / PLATFORM_FLAVOR (hardware platform) - -A *platform* is a family of closely related hardware configurations. A platform -*flavor* is a variant of such configurations. When used together they define the -target hardware on which OP-TEE will be run. - -For instance **PLATFORM=stm PLATFORM_FLAVOR=b2260** will build for the -ST Microelectronics 96boards/cannes2 board, while **PLATFORM=vexpress -PLATFORM_FLAVOR=qemu_virt** will generate code for a para-virtualized ARM -Versatile Express board running on QEMU. - -For convenience, the flavor may be appended to the platform name with a dash, so -**make PLATFORM=stm-b2260** is a shortcut for -**make PLATFORM=stm PLATFORM_FLAVOR=b2260**. Note that in both cases the value -of **$(PLATFORM)** is **stm** in the makefiles. - -Platform-specific source code belongs to `core/arch/$(ARCH)/plat-$(PLATFORM)`, -for instance: `core/arch/arm/plat-vexpress` or `core/arch/arm/plat-stm`. - -### O (output directory) - -All output files go into a platform-specific build directory, which is by default -`out/$(ARCH)-plat-$(PLATFORM)`. - -The output directory has basically the same structure as the source tree. -For instance, assuming **ARCH=arm PLATFORM=stm**, -`core/kernel/panic.c` will compile into `out/arm-plat-stm/core/kernel/panic.o`. - -However, some libraries are compiled several times: once or twice for user -mode, and once for kernel mode. This is because they may be used by the TEE -Core as well as by the Trusted Applications. As a result, the `lib` source -directory gives two or three build directories: `ta_arm{32,64}-lib` and -`core-lib`. - -The output directory also has an `export-ta_arm{32,64}` directory, which -contains: -- All the files needed to build Trusted Applications. - - In `lib/`: **libutee.a** (the GlobalPlatform Internal API), **libutils.a** - (which implements a part of the standard C library), and **libmpa.a** (which - implements multiple precision arithmetic and is required by libutee.a). - - In `include/`: header files for the above libraries - - In `mk/`: **ta_dev_kit.mk**, which is a Make include file with suitable - rules to build a TA, and its dependencies - - `scripts/sign.py`: a Python script used by ta_dev_kit.mk to sign TAs. - - In `src`: **user_ta_header.c**: source file to add a suitable header to the - Trusted Application (as expected by the loader code in the TEE Core) -- Some files needed to build host applications (using the Client API), under - `export-ta_arm{32,64}/host_include`. - -Finally, the build directory contains the auto-generated configuration file -for the TEE Core: `$(O)/include/generated/conf.h` (see below). - -### CROSS_COMPILE* (cross-compiler selection) - -**$(CROSS_COMPILE)** is the prefix used to invoke the (32-bit) cross-compiler -toolchain. -The default value is **arm-linux-gnueabihf-**. This is the variable you want to -change in case you want to use -[ccache](https://ccache.samba.org/) to speed you recompilations: -```shell -$ make CROSS_COMPILE="ccache arm-linux-gnueabihf-" -``` - -If the build includes a mix of 32-bit and 64-bit code, for instance if you -set `CFG_ARM64_core=y` to build a 64-bit secure kernel, then two different -toolchains are used, that are controlled by **$(CROSS_COMPILE32)** and -**$(CROSS_COMPILE64)**. -The default value of **$(CROSS_COMPILE32)** is the value of CROSS_COMPILE, -which defaults to **arm-linux-gnueabihf-** as mentioned above. -The default value of **$(CROSS_COMPILE64)** is **aarch64-linux-gnu-**. - -Examples: -```shell -# FOr this example, select HiKey which supports both 32- and 64-bit builds -$ export PLATFORM=hikey - -# 1. Build everything 32-bit -$ make - -# 2. Same as (1.) but override the toolchain -$ make CROSS_COMPILE="ccache arm-linux-gnueabihf-" - -# 3. Same as (2.) -$ make CROSS_COMPILE32="ccache arm-linux-gnueabihf-" - -# 4. Select 64-bit secure 'core' (and therefore both 32- and 64-bit -# Trusted Application libraries) -$ make CFG_ARM64_core=y - -# 5. Same as (4.) but override the toolchains -$ make CFG_ARM64_core=y \ - CROSS_COMPILE32="ccache arm-linux-gnueabihf-" \ - CROSS_COMPILE64="ccache aarch64-linux-gnu-" -``` - -## Platform-specific configuration and flags - -The following variables are defined in `core/arch/$(ARCH)/$(ARCH).mk`: - -- **$(core-platform-aflags)**, **$(core-platform-cflags)** and - **$(core-platform-cppflags)** are added to the assembler / C compiler - / preprocessor flags for all source files compiled for TEE Core including - the kernel versions of **libmpa.a** and **libutils.a**. -- **$(ta_arm{32,64}-platform-aflags)**, **$(ta_arm{32,64}-platform-cflags)** - and **$(ta_arm{32,64}-platform-cppflags)** are added to the assembler / C - compiler / preprocessor flags when building the user-mode libraries - (**libutee.a**, **libutils.a**, **libmpa.a**) or Trusted Applications. - -The following variables are defined in -`core/arch/$(ARCH)/plat-$(PLATFORM)/conf.mk`: - -- If **$(arm{32,64}-platform-cflags)**, **$(arm{32,64}-platform-aflags)** and - **$(arm{32,64}-platform-cppflags)** are defined their content will be added - to **$(\*-platform-\*flags)** when they are are initialized in - `core/arch/$(ARCH)/$(ARCH).mk` as described above. -- **$(core-platform-subdirs)** is the list of the subdirectories that are - added to the TEE Core. - -## Platform-specific link recipes for the TEE Core - -The file `core/arch/$(ARCH)/plat-$(PLATFORM)/link.mk` contains the rules to -link the TEE Core and perform any related tasks, such as running **objdump** -to produce a dump file. **link.mk** adds files to the **all:** target. - -## Source files - -Each directory that contains source files has a file called `sub.mk`. This -makefile defines the source files that should be included in the build, as well -as any subdirectories that should be processed, too. - -For example: -```Makefile -# core/arch/arm/sm/sub.mk -srcs-y += sm_asm.S -srcs-y += sm.c -``` -```Makefile -# core/sub.mk -subdirs-y += kernel -subdirs-y += mm -subdirs-y += tee -subdirs-y += drivers -``` - -The `-y` suffix is meant to facilitate conditional compilation. -See *Configuration* below. - -`srcs-y` and `subdirs-y` are often not used together in the same `sub.mk`, -because source files are usually alone in leaf directories. But this is not a -hard rule. - -In addition to source files, `sub.mk` may define compiler flags, include -directories and/or configuration variables as explained below. - -## Compiler flags - -Default compiler flags are defined in `mk/compile.mk`. Note that platform-specific flags must not appear in this file which is common to all platforms. - -To add flags for a given source file, you may use the following variables in -`sub.mk`: -* `cflags-<filename>-y` for C files (*.c) -* `aflags-<filename>-y` for assembler files (*.S) -* `cppflags-<filename>-y` for both C and assembler - -For instance: - -```Makefile -# core/lib/libtomcrypt/src/pk/dh/sub.mk -srcs-y += dh.c -cflags-dh.c-y := -Wno-unused-variable -``` -Compiler flags may also be removed, as follows: - -```Makefile -# lib/libutils/isoc/newlib/sub.mk -srcs-y += memmove.c -cflags-remove-memmove.c-y += -Wcast-align -``` - -Some variables apply to libraries only (that is, when using `mk/lib.mk`) -and affect all the source files that belong to the library: `cppflags-lib-y` -and `cflags-lib-y`. - -## Include directories - -Include directories may be added to `global-incdirs-y`, in which case they will -be accessible from all the source files and will be copied to -`export-ta_arm{32,64}/include` and `export-ta_arm{32,64}/host_include`. - -When `sub.mk` is used to build a library, `incdirs-lib-y` may receive additional -directories that will be used for that library only. - -## Configuration variables - -Some features may be enabled, disabled or otherwise controlled at compile time -through makefile variables. Default values are normally provided in makefiles -with the `?=` operator so that their value may be easily overridden by -environment variables. For instance: - -```Makefile -PLATFORM ?= stm -PLATFORM_FLAVOR ?= default -``` - -Some global configuration variables are defined in `mk/config.mk`, but others -may be defined in `sub.mk` when then pertain to a specific library for instance. - -Variables with the `CFG_` prefix are treated in a special -way: their value is automatically reflected in the generated header -file `$(out-dir)/include/generated/conf.h`, after all the included -makefiles have been processed. `conf.h` is automatically included by the -preprocessor when a source file is built. - -Depending on their value, variables may -be considered either boolean or non-boolean, which affects how they are -translated into `conf.h`. - -### Boolean configuration variables - -When a configuration variable controls the presence or absence of a feature, -**y** means *enabled*, while **n**, an empty value or an undefined variable -means *disabled*. For instance, the following commands are equivalent and would -disable feature *CFG_CRYPTO_GCM*: - -```Shell -$ make CFG_CRYPTO_GCM=n -``` -```Shell -$ make CFG_CRYPTO_GCM= -``` -```Shell -$ CFG_CRYPTO_GCM=n make -``` -```Shell -$ export CFG_CRYPTO_GCM=n -$ make -``` - -Configuration variables may then be used directly in `sub.mk` to -trigger conditional compilation: - -```Makefile -# core/lib/libtomcrypt/src/encauth/sub.mk -subdirs-$(CFG_CRYPTO_CCM) += ccm -subdirs-$(CFG_CRYPTO_GCM) += gcm -``` - -When a configuration variable is *enabled* (**y**), `<generated/conf.h>` -contains a macro with the same name as the variable and the value **1**. -If it is *disabled*, however, no macro definition is output. This allows the C -code to use constructs like: - -```C -/* core/lib/libtomcrypt/src/tee_ltc_provider.c */ - -/* ... */ - -#if defined(CFG_CRYPTO_GCM) -struct tee_gcm_state { - gcm_state ctx; /* the gcm state as defined by LTC */ - size_t tag_len; /* tag length */ -}; -#endif -``` - -### Non-boolean configuration variables - -Configuration variables that are not recognized as booleans are simply output -unchanged into `<generated/conf.h>`. For instance: - -```Makefile -$ make CFG_TEE_CORE_LOG_LEVEL=4 -``` -```C -/* out/arm-plat-vexpress/include/generated/conf.h */ - -#define CFG_TEE_CORE_LOG_LEVEL 4 /* '4' */ -``` - -### Configuration dependencies - -Some combinations of configuration variables may not be valid. This should be -dealt with by custom checks in makefiles. `mk/checkconf.h` provides functions -to help detect and deal with such situations. diff --git a/documentation/copyright_and_license_headers.rst b/documentation/copyright_and_license_headers.rst deleted file mode 100644 index 18c17407..00000000 --- a/documentation/copyright_and_license_headers.rst +++ /dev/null @@ -1,39 +0,0 @@ -OP-TEE copyright and license headers -==================================== - -This document defines the format of the copyright and license headers in OP-TEE -source files. Such headers shall comply with the rules described here, which -are compatible with the rules adopted by the Linux kernel community. - -New source files ----------------- - -- (Rule 1.1) Shall contain exactly one SPDX license identifier, which can - express a single or multiple licenses (refer to SPDX_ for syntax details) -- (Rule 1.2) The SPDX license identifier shall be added as a comment line. It - shall be the first possible line in the file which can contain a comment. - The comment style shall depend on the file type: -- (Rule 1.2.1) C source: // SPDX-License-Identifier: <expression> -- (Rule 1.2.2) C header: /* SPDX-License-Identifier: <expression> */ -- (Rule 1.2.3) Assembly: /* SPDX-License-Identifier: <expression> */ -- (Rule 1.2.4) Python, shell: # SPDX-License-Identifier: <expression> -- (Rule 1.3) Shall contain at least one copyright line -- (Rule 1.4) Shall not contain the mention 'All rights reserved' -- (Rule 1.5) Shall not contain any license notice other than the SPDX license - identifier - -Note that files imported from external projects are not new files. The rules -for pre-existing files (below) apply. - -Pre-existing or imported files ------------------------------- - -- (Rule 2.1) SPDX license identifiers shall be added according to the license - notice(s) in the file and the rules above (1.1 and 1.2*) -- (Rule 2.2) It is recommended that license notices be removed once the - corresponding identifier has been added. Note however that this may only be - done by the copyright holder(s) of the file. -- (Rule 2.3) Similar to 2.2, and subject to the same conditions, the text: - "All rights reserved" shall be removed also. - -.. _SPDX: https://spdx.org/licenses/ diff --git a/documentation/crypto.md b/documentation/crypto.md deleted file mode 100644 index 3cb9c742..00000000 --- a/documentation/crypto.md +++ /dev/null @@ -1,174 +0,0 @@ -# OP-TEE crypto implementation - -This document describes how the TEE Cryptographic Operations API is implemented, -how the default crypto provider may be configured at compile time, and how it may -be replaced by another implementation. - -## Overview - -There are several layers from the Trusted Application to the actual crypto -algorithms. Most of the crypto code runs in kernel mode inside the TEE core. - -Here is a schematic view of a typical call to the crypto API. The numbers in -square brackets ([1], [2]...) refer to the sections below. - - some_function() (Trusted App) - [1] TEE_*() User space (libutee.a) - ------- utee_*() ---------------------------------------------- - [2] tee_svc_*() Kernel space - [3] crypto_*() (libtomcrypt.a and crypto.c) - [4] /* LibTomCrypt */ (libtomcrypt.a) - -## The TEE Cryptographic Operations API [1] - -OP-TEE implements the TEE Internal API defined by the GlobalPlatform association -in the *TEE Internal API Specification* (GPD_SPE_010). This includes -cryptographic functions that span various cryptographic needs: message digests, -symmetric ciphers, message authentication codes (MAC), authenticated encryption, -asymmetric operations (encryption/decryption or signing/verifying), key -derivation, and random data generation. These functions make up the TEE -Cryptographic Operations API. - -The Internal API is implemented in -[tee_api_operations.c](../lib/libutee/tee_api_operations.c), which is -compiled into a static library: `${O}/ta_arm{32,64}-lib/libutee/libutee.a`. - -Most API functions perform some parameter checking and manipulations, then -invoke some **utee_\*** function to switch to kernel mode and perform the -low-level work. - -The **utee_\*** functions are declared in -[utee_syscalls.h](../lib/libutee/include/utee_syscalls.h) -and implemented in -[utee_syscalls_asm.S](../lib/libutee/arch/arm/utee_syscalls_asm.S). -They are simple system call wrappers which use the **SVC** -instruction to switch to the appropriate system service in the OP-TEE kernel. - -## The crypto services [2] - -All cryptography-related system calls are declared in -[tee_svc_cryp.h](../core/include/tee/tee_svc_cryp.h) and implemented in -[tee_svc_cryp.c](../core/tee/tee_svc_cryp.c). -In addition to dealing with the usual work required at the user/kernel interface -(checking parameters and copying memory buffers between user and kernel space), -the system calls invoke a private abstraction layer: the **Crypto API**, -which is declared in [crypto.h](../core/include/crypto/crypto.h). -It serves two main purposes: - -1. Allow for alternative implementations, such as hardware-accelerated versions. -2. Provide an easy way to disable some families of algorithms at compile-time - to save space. See *LibTomCrypt* below. - -## crypto_*() [3] - -The **crypto_*()** functions implement the actual algorithms and helper -functions. The TEE Core has one global active implementation of this interface. -The default implementation, mostly based on -[LibTomCrypt](https://github.com/libtom/libtomcrypt), is as follows: - -```c -/* core/crypto/crypto.c */ - -/* - * Default implementation for all functions in crypto.h - */ - -#if !defined(_CFG_CRYPTO_WITH_HASH) -TEE_Result crypto_hash_get_ctx_size(uint32_t algo __unused, - size_t *size __unused) -{ - return TEE_ERROR_NOT_IMPLEMENTED; -} -... -#endif /*_CFG_CRYPTO_WITH_HASH*/ - -/* core/lib/libtomcrypt/tee_ltc_provider.c */ - -#if defined(_CFG_CRYPTO_WITH_HASH) -TEE_Result crypto_hash_get_ctx_size(uint32_t algo, size_t *size) -{ - /* ... */ - return TEE_SUCCESS; -} - -#endif /*_CFG_CRYPTO_WITH_HASH*/ - -``` - -As shown above, families of algorithms can be disabled and -[crypto.c](../core/crypto/crypto.c) will provide default null -implementations that will return **TEE_ERROR_NOT_IMPLEMENTED**. - -## Public/private key format - -**<crypto/crypto.h>** uses implementation-specific types to hold key data -for asymmetric algorithms. For instance, here is how a public RSA key is -represented: - -```c -/* core/include/crypto/crypto.h */ - -struct rsa_public_key { - struct bignum *e; /* Public exponent */ - struct bignum *n; /* Modulus */ -}; -``` - -This is also how such keys are stored inside the TEE object attributes -(**TEE_ATTR_RSA_PUBLIC_KEY** in this case). - -**struct bignum** is an opaque type, known to the underlying implementation -only. **struct bignum_ops** provides functions so that the system services can -manipulate data of this type. This includes allocation/deallocation, copy, and -conversion to or from the big endian binary format. - - -```c -/* core/include/crypto/crypto.h */ - -struct bignum *crypto_bignum_allocate(size_t size_bits); -TEE_Result crypto_bignum_bin2bn(const uint8_t *from, size_t fromsize, - struct bignum *to); -void crypto_bignum_bn2bin(const struct bignum *from, uint8_t *to); -/*...*/ - -``` - -## LibTomCrypt [4] - -Some algorithms may be disabled at compile time if they are not needed, in order -to reduce the size of the OP-TEE image and reduces its memory usage. This is done -by setting the appropriate configuration variable. For example: - - $ make CFG_CRYPTO_AES=n # disable AES only - $ make CFG_CRYPTO_{AES,DES}=n # disable symmetric ciphers - $ make CFG_CRYPTO_{DSA,RSA,DH,ECC}=n # disable public key algorithms - $ make CFG_CRYPTO=n # disable all algorithms - -Please refer to [core/lib/libtomcrypt/sub.mk](../core/lib/libtomcrypt/sub.mk) -for the list of all supported variables. - -Note that the application interface is **not** modified when algorithms are -disabled. This means, for instance, that the functions **TEE_CipherInit()**, -**TEE_CipherUpdate()** and **TEE_CipherFinal()** would remain present in -`libutee.a` even if all symmetric ciphers are disabled (they would simply -return **TEE_ERROR_NOT_IMPLEMENTED**). - -## How to add a new crypto implementation - -To add a new implementation, the default one in -[core/lib/libtomcrypt](../core/lib/libtomcrypt) in combination with what is -in [core/crypto](../core/crypto) should be used as a reference. - -Here are the main things to consider when adding a new crypto provider: - -- Put all the new code in its own directory under `core/lib` unless it is - code that will be used regardless of which crypto provider is in use. - How we are dealing with AES-GCM in [core/crypto](../core/crypto) could - serve as an example. -- Avoid modifying [tee_svc_cryp.c](../core/tee/tee_svc_cryp.c). It should not be - needed. -- Although not all crypto families need to be defined, all are required for - compliance to the GlobalPlatform specification. -- If you intend to make some algorithms optional, please try to re-use the same - names for configuration variables as the default implementation. diff --git a/documentation/dt-bindings/README.txt b/documentation/dt-bindings/README.txt deleted file mode 100644 index 379854b2..00000000 --- a/documentation/dt-bindings/README.txt +++ /dev/null @@ -1,9 +0,0 @@ -This directory shall store the device tree bindings documentation. - -When a binding is already described in the Linux kernel source tree, -please refer there for bindings information. Latest Linux kernel release -is the reference for DT bindings. - -For the bindings not described in the the Linux kernel source tree, one can -find here the expected description. Please use the conventional format -for DT bindings documentation, currently plain ASCII text files. diff --git a/documentation/extensions/crypto_concat_kdf.md b/documentation/extensions/crypto_concat_kdf.md deleted file mode 100644 index cbdfff16..00000000 --- a/documentation/extensions/crypto_concat_kdf.md +++ /dev/null @@ -1,111 +0,0 @@ -# Concatenation Key Derivation Function (Concat KDF) - -This document describes the OP-TEE implementation of the key derivation function -specified in section 5.8.1 of NIST publication [SP 800-56A](http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf), *Recommendation for Pair-Wise Key Establishment Schemes Using Discrete Logarithm Cryptography*. This function is known as *Concatenation KDF* or *Concat -KDF*. - -You may disable this extension by setting the following configuration variable -in `conf.mk`: - - CFG_CRYPTO_CONCAT_KDF := n - -## Implementation notes - -All key and parameter sizes must be multiples of 8 bits. That is: -- Input parameters: the shared secret (*Z*) and *OtherInfo* -- Output parameter: the derived key (*DerivedKeyingMaterial*) - -In addition, the maximum size of the derived key is limited by the size of an -object of type TEE_TYPE_GENERIC_SECRET (512 bytes). - -This implementation does *not* enforce any requirement on the content of the -*OtherInfo* parameter. It is the application's responsibility to make sure this -parameter is constructed as specified by the NIST specification if compliance -is desired. - - -## API extension - -To support the Concat KDF, the *GlobalPlatform TEE Internal Core API Specification -v1.1* was extended with new algorithm descriptors, new object types, and new -object attributes as described below. - -### p.95 Add new object type to TEE_PopulateTransientObject - -The following entry shall be added to Table 5-8: - -Object type | Parts -:---------------------|:-------------------------------------------- -TEE_TYPE_CONCAT_KDF_Z | The TEE_ATTR_CONCAT_KDF_Z part (input shared secret) must be provided. - -### p.121 Add new algorithms for TEE_AllocateOperation - -The following entry shall be added to Table 6-3: - -Algorithm | Possible Modes -:---------------------------|:-------------- -TEE_ALG_CONCAT_KDF_SHA1_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA224_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA256_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA384_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA512_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA512_DERIVE_KEY | TEE_MODE_DERIVE - -### p.126 Explain usage of HKDF algorithms in TEE_SetOperationKey - -In the bullet list about operation mode, the following shall be added: - - * For the Concat KDF algorithms, the only supported mode is TEE_MODE_DERIVE. - -### p.150 Define TEE_DeriveKey input attributes for new algorithms - -The following sentence shall be deleted: - - The TEE_DeriveKey function can only be used with the algorithm - TEE_ALG_DH_DERIVE_SHARED_SECRET - -The following entry shall be added to Table 6-7: - -Algorithm | Possible operation parameters -:---------------------------|:----------------------------- -TEE_ALG_CONCAT_KDF_SHA1_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA224_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA256_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA384_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA512_DERIVE_KEY <br> TEE_ALG_CONCAT_KDF_SHA512_DERIVE_KEY | TEE_ATTR_CONCAT_KDF_DKM_LENGTH: up to 512 bytes. This parameter is mandatory. <br> TEE_ATTR_CONCAT_KDF_OTHER_INFO - -### p.152 Add new algorithm identifiers - -The following entries shall be added to Table 6-8: - -Algorithm | Identifier -:------------------------------------|:---------- -TEE_ALG_CONCAT_KDF_SHA1_DERIVE_KEY | 0x800020C1 -TEE_ALG_CONCAT_KDF_SHA224_DERIVE_KEY | 0x800030C1 -TEE_ALG_CONCAT_KDF_SHA256_DERIVE_KEY | 0x800040C1 -TEE_ALG_CONCAT_KDF_SHA384_DERIVE_KEY | 0x800050C1 -TEE_ALG_CONCAT_KDF_SHA512_DERIVE_KEY | 0x800060C1 - -### p.154 Define new main algorithm - -In Table 6-9 in section 6.10.1, a new value shall be added to the value column -for row bits [7:0]: - -Bits | Function | Value -:----------|:-----------------------------------------------|:----------------- -Bits [7:0] | Identifiy the main underlying algorithm itself | ...<br>0xC1: Concat KDF - -The function column for bits[15:12] shall also be modified to read: - -Bits | Function | Value -:------------|:---------------------------------------------|:----------- -Bits [15:12] | Define the message digest for asymmetric signature algorithms or Concat KDF | - -### p.155 Add new object type for Concat KDF input shared secret - -The following entry shall be added to Table 6-10: - -Name | Identifier | Possible sizes -:---------------------------------|:-----------|:-------------------------------- -TEE_TYPE_CONCAT_KDF_Z | 0xA10000C1 | 8 to 4096 bits (multiple of 8) - -### p.156 Add new operation attributes for Concat KDF - -The following entries shall be added to Table 6-11: - -Name | Value | Protection | Type | Comment -:----------------------------------|:-----------|:-----------|:------|:-------- -TEE_ATTR_CONCAT_KDF_Z | 0xC00001C1 | Protected | Ref | The shared secret (*Z*) -TEE_ATTR_CONCAT_KDF_OTHER_INFO | 0xD00002C1 | Public | Ref | *OtherInfo* -TEE_ATTR_CONCAT_KDF_DKM_LENGTH | 0xF00003C1 | Public | Value | The length (in bytes) of the derived keying material to be generated, maximum 512. This is *KeyDataLen* / 8. diff --git a/documentation/extensions/crypto_hkdf.md b/documentation/extensions/crypto_hkdf.md deleted file mode 100644 index b60a980e..00000000 --- a/documentation/extensions/crypto_hkdf.md +++ /dev/null @@ -1,99 +0,0 @@ -# OP-TEE HKDF key derivation support - -OP-TEE implements the *HMAC-based Extract-and-Expand Key Derivation Function -(HKDF)* specified in [RFC 5869](http://tools.ietf.org/html/rfc5869). This -file documents the extensions to the *GlobalPlatform TEE Internal Core API -Specification v1.1* that were implemented to support this algorithm. Trusted -Applications should include `<tee_api_defines_extensions.h>` to import the -definitions. - -Note that the implementation follows the recommendations of version 1.1 of the -specification for adding new algorithms. It should make it compatible with -future changes to the official specification. - -You can disable this extension by setting the following in `conf.mk`: - - CFG_CRYPTO_HKDF := n - -## p.95 Add new object type to TEE_PopulateTransientObject - -The following entry shall be added to Table 5-8: - -Object type | Parts -:-----------------|:-------------------------------------------- -TEE_TYPE_HKDF_IKM | The TEE_ATTR_HKDF_IKM (Input Keying Material) part must be provided. - -## p.121 Add new algorithms for TEE_AllocateOperation - -The following entry shall be added to Table 6-3: - -Algorithm | Possible Modes -:---------------------------|:-------------- -TEE_ALG_HKDF_MD5_DERIVE_KEY <br> TEE_ALG_HKDF_SHA1_DERIVE_KEY <br> TEE_ALG_HKDF_SHA224_DERIVE_KEY <br> TEE_ALG_HKDF_SHA256_DERIVE_KEY <br> TEE_ALG_HKDF_SHA384_DERIVE_KEY <br> TEE_ALG_HKDF_SHA512_DERIVE_KEY <br> TEE_ALG_HKDF_SHA512_DERIVE_KEY | TEE_MODE_DERIVE - -## p.126 Explain usage of HKDF algorithms in TEE_SetOperationKey - -In the bullet list about operation mode, the following shall be added: - - * For the HKDF algorithms, the only supported mode is TEE_MODE_DERIVE. - -## p.150 Define TEE_DeriveKey input attributes for new algorithms - -The following sentence shall be deleted: - - The TEE_DeriveKey function can only be used with the algorithm - TEE_ALG_DH_DERIVE_SHARED_SECRET - -The following entry shall be added to Table 6-7: - -Algorithm | Possible operation parameters -:---------------------------|:----------------------------- -TEE_ALG_HKDF_MD5_DERIVE_KEY <br> TEE_ALG_HKDF_SHA1_DERIVE_KEY <br> TEE_ALG_HKDF_SHA224_DERIVE_KEY <br> TEE_ALG_HKDF_SHA256_DERIVE_KEY <br> TEE_ALG_HKDF_SHA384_DERIVE_KEY <br> TEE_ALG_HKDF_SHA512_DERIVE_KEY <br> TEE_ALG_HKDF_SHA512_DERIVE_KEY | TEE_ATTR_HKDF_OKM_LENGTH: Number of bytes in the Output Keying Material <br> TEE_ATTR_HKDF_SALT (optional) Salt to be used during the extract step <br> TEE_ATTR_HKDF_INFO (optional) Info to be used during the expand step <br> - -## p.152 Add new algorithm identifiers - -The following entries shall be added to Table 6-8: - -Algorithm | Identifier -:------------------------------|:---------- -TEE_ALG_HKDF_MD5_DERIVE_KEY | 0x800010C0 -TEE_ALG_HKDF_SHA1_DERIVE_KEY | 0x800020C0 -TEE_ALG_HKDF_SHA224_DERIVE_KEY | 0x800030C0 -TEE_ALG_HKDF_SHA256_DERIVE_KEY | 0x800040C0 -TEE_ALG_HKDF_SHA384_DERIVE_KEY | 0x800050C0 -TEE_ALG_HKDF_SHA512_DERIVE_KEY | 0x800060C0 - -## p.154 Define new main algorithm - -In Table 6-9 in section 6.10.1, a new value shall be added to the value column -for row bits [7:0]: - -Bits | Function | Value -:----------|:-----------------------------------------------|:----------------- -Bits [7:0] | Identifiy the main underlying algorithm itself | ...<br>0xC0: HKDF - -The function column for bits[15:12] shall also be modified to read: - -Bits | Function | Value -:------------|:---------------------------------------------|:----------- -Bits [15:12] | Define the message digest for asymmetric signature algorithms or HKDF | - -## p.155 Add new object type for HKDF input keying material - -The following entry shall be added to Table 6-10: - -Name | Identifier | Possible sizes -:-----------------|:-----------|:-------------------------------- -TEE_TYPE_HKDF_IKM | 0xA10000C0 | 8 to 4096 bits (multiple of 8) - -## p.156 Add new operation attributes for HKDF salt and info - -The following entries shall be added to Table 6-11: - -Name | Value | Protection | Type | Comment -:------------------------|:-----------|:-----------|:------|:-------- -TEE_ATTR_HKDF_IKM | 0xC00001C0 | Protected | Ref | -TEE_ATTR_HKDF_SALT | 0xD00002C0 | Public | Ref | -TEE_ATTR_HKDF_INFO | 0xD00003C0 | Public | Ref | -TEE_ATTR_HKDF_OKM_LENGTH | 0xF00004C0 | Public | Value | - diff --git a/documentation/extensions/crypto_pbkdf2.md b/documentation/extensions/crypto_pbkdf2.md deleted file mode 100644 index 5ce3c4ad..00000000 --- a/documentation/extensions/crypto_pbkdf2.md +++ /dev/null @@ -1,94 +0,0 @@ -# PKCS #5 v2.0 Key Derivation Function 2 (PBKDF2) - -This document describes the OP-TEE implementation of the key derivation function -specified in [RFC 2898](https://www.ietf.org/rfc/rfc2898.txt) section 5.2. This -RFC is a republication of PKCS #5 v2.0 from RSA Laboratories' Public-Key -Cryptography Standards (PKCS) series. - -You may disable this extension by setting the following configuration variable -in `conf.mk`: - - CFG_CRYPTO_PBKDF2 := n - -## API extension - -To support PBKDF2, the *GlobalPlatform TEE Internal Core API Specification -v1.1* was extended with a new algorithm descriptor, new object types, and new -object attributes as described below. - -### p.95 Add new object type to TEE_PopulateTransientObject - -The following entry shall be added to Table 5-8: - -Object type | Parts -:------------------------|:-------------------------------------------- -TEE_TYPE_PBKDF2_PASSWORD | The TEE_ATTR_PBKDF2_PASSWORD part must be provided. - -### p.121 Add new algorithms for TEE_AllocateOperation - -The following entry shall be added to Table 6-3: - -Algorithm | Possible Modes -:---------------------------|:-------------- -TEE_ALG_PBKDF2_HMAC_SHA1_DERIVE_KEY | TEE_MODE_DERIVE - -### p.126 Explain usage of PBKDF2 algorithm in TEE_SetOperationKey - -In the bullet list about operation mode, the following shall be added: - - * For the PBKDF2 algorithm, the only supported mode is TEE_MODE_DERIVE. - -### p.150 Define TEE_DeriveKey input attributes for new algorithms - -The following sentence shall be deleted: - - The TEE_DeriveKey function can only be used with the algorithm - TEE_ALG_DH_DERIVE_SHARED_SECRET - -The following entry shall be added to Table 6-7: - -Algorithm | Possible operation parameters -:---------------------------|:----------------------------- -TEE_ALG_PBKDF2_HMAC_SHA1_DERIVE_KEY | TEE_ATTR_PBKDF2_DKM_LENGTH: up to 512 bytes. This parameter is mandatory. <br> TEE_ATTR_PBKDF2_SALT <br> TEE_ATTR_PBKDF2_ITERATION_COUNT: This parameter is mandatory. - -### p.152 Add new algorithm identifiers - -The following entries shall be added to Table 6-8: - -Algorithm | Identifier -:------------------------------------|:---------- -TEE_ALG_PBKDF2_HMAC_SHA1_DERIVE_KEY | 0x800020C2 - -### p.154 Define new main algorithm - -In Table 6-9 in section 6.10.1, a new value shall be added to the value column -for row bits [7:0]: - -Bits | Function | Value -:----------|:-----------------------------------------------|:----------------- -Bits [7:0] | Identifiy the main underlying algorithm itself | ...<br>0xC2: PBKDF2 - -The function column for bits[15:12] shall also be modified to read: - -Bits | Function | Value -:------------|:---------------------------------------------|:----------- -Bits [15:12] | Define the message digest for asymmetric signature algorithms or PBKDF2 | - -### p.155 Add new object type for PBKDF2 password - -The following entry shall be added to Table 6-10: - -Name | Identifier | Possible sizes -:---------------------------------|:-----------|:-------------------------------- -TEE_TYPE_PBKDF2_PASSWORD | 0xA10000C2 | 8 to 4096 bits (multiple of 8) - -### p.156 Add new operation attributes for Concat KDF - -The following entries shall be added to Table 6-11: - -Name | Value | Protection | Type | Comment -:----------------------------------|:-----------|:-----------|:------|:-------- -TEE_ATTR_PBKDF2_PASSWORD | 0xC00001C2 | Protected | Ref | -TEE_ATTR_PBKDF2_SALT | 0xD00002C2 | Public | Ref | -TEE_ATTR_PBKDF2_ITERATION_COUNT | 0xF00003C2 | Public | Value | -TEE_ATTR_PBKDF2_DKM_LENGTH | 0xF00004C2 | Public | Value | The length (in bytes) of the derived keying material to be generated, maximum 512. diff --git a/documentation/extensions/crypto_rsassa_pkcs1_v1_5.md b/documentation/extensions/crypto_rsassa_pkcs1_v1_5.md deleted file mode 100644 index 9b1e65df..00000000 --- a/documentation/extensions/crypto_rsassa_pkcs1_v1_5.md +++ /dev/null @@ -1,20 +0,0 @@ -# PKCS#1 v1.5 RSASSA without hash OID - -This extension adds `TEE_ALG_RSASSA_PKCS1_V1_5` to allow signing and verifying -messages with `RSASSA-PKCS1-v1_5` ([RFC 3447](https://tools.ietf.org/html/rfc3447#section-8.2)) -without including the OID of the hash in the signature. Trusted Applications -should include `<tee_api_defines_extensions.h>` to import the definitions. - -The extension can be used by defining `CFG_CRYPTO_RSASSA_NA1`. - -# API extensions - -The TEE Internal Core API was extended with a new algorithm descriptor. - -Algorithm | Possible Modes -:---------------------------|:-------------- -TEE_ALG_RSASSA_PKCS1_V1_5 | TEE_MODE_SIGN <br> TEE_MODE_VERIFY - -Algorithm | Identifier -:------------------------------|:---------- -TEE_ALG_RSASSA_PKCS1_V1_5 | 0xF0000830 diff --git a/documentation/extensions/extensions.md b/documentation/extensions/extensions.md deleted file mode 100644 index 1b2bae12..00000000 --- a/documentation/extensions/extensions.md +++ /dev/null @@ -1,33 +0,0 @@ -# General Extensions to the GlobalPlatform TEE Internal Core API - -This document describes the OP-TEE extensions introduced with respect to the -GlobalPlatform TEE Internal Core API Specifications v1.1. - -Specific extensions documentation are part of: -* Cryptographic Extensions - * [Concatenation Key Derivation](crypto_concat_kdf.md) - * [HMAC Key Derivation](crypto_hkdf.md) - * [Public-Key Key Derivation](crypto_pbkdf2.md) - * [PKCS#1 v1.5 RSA sign/verify without the hash OID](crypto_rsassa_pkcs1_v1_5.md) - - -# Cache Maintenance Support -Following functions have been introduced in order to operate with cache: - - TEE_Result TEE_CacheClean(char *buf, size_t len); - TEE_Result TEE_CacheFlush(char *buf, size_t len); - TEE_Result TEE_CacheInvalidate(char *buf, size_t len); - -These functions are available to any Trusted Application defined with the flag TA_FLAG_CACHE_MAINTENANCE sets on. When not set, each function returns the error code TEE_ERROR_NOT_SUPPORTED. - -Within these extensions, a Trusted Application is able to operate on the data cache, with the following specification: - -Function | Description -:---------------------|:---------- -TEE_CacheClean() | Write back to memory any dirty data cache lines. The line is marked as not dirty. The valid bit is unchanged -TEE_CacheFlush() | Purges any valid data cache lines. Any dirty cache lines are first written back to memory, then the cache line is invalidated. -TEE_CacheInvalidate() | Invalidate any valid data cache lines. Any dirty line are not written back to memory. - -In the following 2 cases, the error code TEE_ERROR_ACCESS_DENIED is returned: -* the memory range has not the write access, that is TEE_MEMORY_ACCESS_WRITE is not set. -* the memory is not a User Space memory diff --git a/documentation/external_libraries.rst b/documentation/external_libraries.rst deleted file mode 100644 index 6554feab..00000000 --- a/documentation/external_libraries.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. SPDX-License-Identifier: BSD-2-Clause -.. _external_libraries: - -================== -External libraries -================== - -OP-TEE OS contains code imported from external libraries such as: - -- LibTomCrypt_ in ``core/lib/libtomcrypt/`` -- Newlib_ in ``lib/libutils/isoc/newlib/`` -- `mbed TLS`_ in ``lib/libmbedtls/`` - -Historically and for convenience, the imported code was directly committed into -the OP-TEE source tree. Doing otherwise, such as using Git submodules, would -have made things more complex and error-prone for OP-TEE users and developers -and was not deemed necessary. - -While this choice is good for smaller libraries or the ones that do not change -much, it can be problematic for larger libraries which need to be synchronized -with upstream occasionally, especially as local changes accumulate in the -library. - -Therefore, this document defines a process that should hopefully help import -and maintain any substantial piece of external code into the OP-TEE Git. - -mbed TLS version 2.6.1 is used as an example. - -Importing code --------------- - -1. An OP-TEE maintainer creates a branch: ``import/mbedtls-2.6.1`` from current - ``master``. -2. A contributor creates a pull request against this branch, with the following - commits (see `PR#2338`_ for the real example): - - - ``Import mbedtls-2.6.1``. This is the base commit which imports the code - unmodified from the upstream project. Some files may be omitted but no - other change is allowed. In the commit description, the upstream commit or - tag should be clearly identified. - - ``<Local change #1>`` - - ``<Local change #2>``... A number of local modifications should follow, - typically some local adaptations to configuration and/or build files but - possibly also some modifications that are needed so that OP-TEE may use - the library. These local changes will be carried to newer versions of the - imported library when needed. - -3. The pull request is reviewed and merged normally (into the - ``import/mbedtls-2.6.1`` branch). -4. The contributor creates a pull request against ``master`` which uses the - imported library to add some feature. The pull request typically contains - the following commits: - - - ``<Preparatory work>``... - - ``Squashed commit importing mbedtls-2.6.1 source``. As the description - suggests, this adds the contents committed in step 2 above as a single - commit. - - ``<Enable the new feature>`` - -5. The pull request is reviewed and merged normally. - -Adding further local features or fixes to the imported library --------------------------------------------------------------- - -Whenever a change has to be made locally to the imported library, the import -branch should be modified first. The steps are: - -1. A contributor creates a pull request against the import branch: - ``import/mbedtls-2.6.1``. It may happen that the proposed change depends on - commits that are in master but not in the import branch, which would cause - the CI to fail. In this case, it is desirable that the contributor asks a - maintainer to **merge** (not rebase) ``optee_os master`` into the import - branch. The history of the import branch can still be shown easily with - ``git log --first-parent import/mbedtls-2.6.1``. -2. The pull request is reviewed and merged into the import branch. -3. The contributor creates a pull request against ``master``. The commits - are cherry-picks of those that were merged into the import branch, plus - any additional changes in ``optee_os`` that may be required. -4. The pull request is reviewed and merged into the master branch. - -Updating the imported code to a newer upstream revision ------------------------------------------------------- - -When it is time to update the imported library, say to an hypothetic mbed TLS -version 2.6.2, a similar process is applied again: - -1. An OP-TEE maintainter creates a branch: ``import/mbedtls-2.6.2`` from - current ``master``. -2. A contributor creates a pull request against this new branch with the - following patches: - - - ``Remove all files under lib/libmbedtls`` - - ``Import mbed TLS 2.6.2`` (some unneeded files may be omitted) - - Cherry-pick all the patches from ``import/mbedtls-2.6.1`` (except ``Import - mbedtls-2.6.1`` of course). - -3. The pull request is reviewed and merged normally (into the - ``import/mbedtls-2.6.2`` branch) -4. The contributor creates a pull request against master: - - - ``Squashed commit upgrading to mbedtls-2.6.2``. This is a squashed merge - to master of the commits in the ``import/mbedtls-2.6.2`` branch. - -5. The pull request is reviewed and merged normally. - -.. _LibTomCrypt: https://github.com/libtom/libtomcrypt -.. _Newlib: https://sourceware.org/newlib/ -.. _`mbed TLS`: https://tls.mbed.org/ -.. _`PR#2338`: https://github.com/OP-TEE/optee_os/pull/2338 diff --git a/documentation/file_structure.md b/documentation/file_structure.md deleted file mode 100644 index 77d9a8a7..00000000 --- a/documentation/file_structure.md +++ /dev/null @@ -1,67 +0,0 @@ -# Structure of files - -## Top level directories -Directory | Description -:---------|:------------ -/core | Files that are only used building TEE Core -/lib | Files that are used both when building TEE Core and TAs -/ta | Files that are only used when building TAs -/mk | Makefiles supporting the build system -/tmp-stuff| Temporary stuff that will be removed before the final commit is made -/scripts | Helper scripts for miscellaneous tasks -/out | Created when building unless a different out directory is specified with O=... on the command line - -## Structure of /core -Directory | Description -:---------|:------------ -/arch | Architecture and platform specific files -/include | Header files of resources exported by the core -/lib | Generic libraries that are likely to be replaced in a final product -/mm | Generic memory management, currently empty -/tee | Generic TEE files - -## Structure of /core/include -Directory | Description -:---------|:------------ -/drivers | Include files exposing API for /core/drivers files -/dt-bindings | Include files for the device tree bindings - -## Structure of /core/arch -Directory | Description -:---------|:------------ -/arm | ARMv7 and Aarch32 specific architecture and platform specific files - -## Structure of /core/arch/arm -Directory | Description -:---------|:------------ -/dts | Device tree source files -/include | Include files used in rest of TEE core but not in any supporting libraries -/kern | Low level and core parts of TEE Core -/mm | Memory management -/tee | TEE files -/sm | Secure Monitor -/plat-foo | Specific files for the 'foo' platform - -## Structure of /core/arch/arm/include -Directory | Description -:---------|:------------ -/kern | Include files exposing API for /core/arch/arm/kern files -/kta | Include files exposing the KTA API that is mainly used by kernel TAs -/mm | Include files exposing API for /core/arch/arm/mm files -/rom | Old ROM files that should be removed before going public -/sm | Include files exposing API for Secure Monitor - -## Structure of /core/lib/lib{crypto,sla} -Directory | Description -:---------|:------------ -/ | Source files for the library -/include | Include files exposing the API of the library - -## Structure of /lib/libutils -Directory | Description -:---------|:------------ -/ | Source file for the library -/arch | Architecture specific source files -/arch/arm | ARMv7 and Aarch32 specific source files -/arch/arm/include | ARMv7 and Aarch32 specific include files -/include | Include files exposing the API of the library diff --git a/documentation/github.md b/documentation/github.md deleted file mode 100644 index 5e9b2317..00000000 --- a/documentation/github.md +++ /dev/null @@ -1,213 +0,0 @@ -GitHub usage -============ - -This document describes how to use GitHub for OP-TEE development and -contributions. - - -GitHub Setup ------------- - -### Setting up an account - -You do not need to own a GitHub account in order to clone a repository. But if -you want to contribute, you need to create an account at -[github.com](https://github.com) first. Note that a free plan is sufficient to -collaborate. - -SSH is recommended to access your GitHub repositories securely and without -supplying your username and password each time you pull or push something. -To configure SSH for GitHub, please refer to [Connecting to GitHub with SSH]( -https://help.github.com/articles/connecting-to-github-with-ssh/). - -### Forking - -Only owners of the OP-TEE projects have write permission to the Git -repositories of those projects. Contributors should *fork* -`OP-TEE/optee_os.git` into their own account, then work on this forked -repository. The complete documentation about *forking* can be found at -[Fork A Repo](https://help.github.com/articles/fork-a-repo). - -Note that the fork only has to be performed once. - -Contributing ------------- -In the following: - -* *myaccount* stands for the name of your GitHub account. -* It is assumed you have configured SSH keys so that the `git` command can -fetch and push code to your GitHub repositories. Otherwise, your GitHub -credentials (email address and password) will be asked for each `git push` -command. - -### Cloning the sources - -To obtain a local copy of your `optee_os` project, do: - - # Clone the forked repository - git clone git@github.com:myaccount/optee_os - - # Add a remote called "upstream" which is the official OP-TEE Git - cd optee_os - git remote add upstream https://github.com/OP-TEE/optee_os - - # Retrieve the gits - git fetch --all - -The above steps are enough to be able to build OP-TEE OS, make some changes, -and optionally publish (or "push") them to your GitHub account. -Pushing commits to your account allows you to later create "pull requests" -against the official OP-TEE repository (called "upstream"), if you would -like to contribute your changes back to the project. - -However, please note that [optee_os](https://github.com/OP-TEE/optee_os]) is -only a fraction of the software needed to run an OP-TEE environment. As such, -OP-TEE developers typically have to deal with a forest of Git trees including -[optee_client](https://github.com/OP-TEE/optee_client]), the Linux kernel, -ARM Trusted Firmware, test applications and other things. For this reason, it -is recommended that you check the -[OP-TEE build project](https://github.com/OP-TEE/build). This project contains -the complete source code required to build working OP-TEE environments for -several platforms. You may then apply the instructions given here to the -`optee_os` repository that is checked out as a part of the main project. Some -adjustments will be needed, though, because of the way the `repo` tool sets up -the Git repositories. - -### Contributing - -The typical workflow to make a change to the OP-TEE OS code and push it to -your GitHub account is as follows. - - # Update your local references to upstream branches - git fetch upstream - # Switch to the local master branch - git checkout master - # Update with the latest commits from upstream - # WARNING: this command will lose any work you may have committed - # on your local "master" branch or may have in your working area. - # (In this work flow it is assumed local master is only ever used as a - # copy of upstream master) - git reset --hard upstream/master - # Create a feature branch to receive your changes, based on master - git checkout -b my_new_feature - ... Code, build, test, debug, repeat ... - ... Stage your changes with git add and/or git rm etc. ... - # Commit your changes locally (-s adds your Signed-off-by: tag) - git commit -s - -We expect commit messages to mostly follow the [Linux kernel recommendations]( -https://www.kernel.org/doc/Documentation/process/submitting-patches.rst). -Please use the output of `git log` in the `optee_os` repository as a source of -inspiration. The important points are: - -- The subject line should explain *what* the patch does as precisely as -possible. It is usually prefixed with keywords indicating which part of the -code is affected, but not always. Avoid lines longer than 80 characters. -- The commit description should give more details on *what* is changed, and -explain *why* it is done. Indication on how to enable and use some particular -feature can be useful, too. Try to limit line length to 72 characters, except -when pasting some error message (compiler diagnostic etc.). Long lines are -allowed to accommodate URLs, too (preferably use URLs in a Fixes: or Link: -tag). -- The commit message must end with a blank line followed by some tags, -including your sign-off: - - Signed-off-by: Your Name <your.email@some.domain> - - By applying such a tag to your commit, you are effectively declaring that your -contribution follows the terms stated by -[Notice - Contributions](../Notice.md#contributions). Other tags may follow, -such as: - - Fixes: <some bug URL> - Fixes: 0123456789ab ("Some commit subject") - Link: <some useful URL> - -- When citing a previous commit, whether in the text body or in a Fixes: tag, -always use the format shown above (12 hexadecimal digits prefix of the commit -SHA1, followed by the commit subject in double quotes and parentheses). - -Always split your changes into logical steps and create one commit for each -step. - -Then the contribution is pushed on the forked repository with: - - git push - -The pull-request can be created through the GitHub interface. Documentation -can be found at -[Using Pull Requests](https://help.github.com/articles/using-pull-requests) and -the *Collaborating* section of [help.github.com](https://help.github.com<). - -It may be that you will get comments from reviewers on the commit(s) you provided. -If so happens, you will need to address the comments and you might end up having -to upload additional commits. If possible, create one or several fixup commit for -each initial commit that has to be changed. Doing so makes it easier for -reviewers to see what has changed and also for you when it is time to squash -commits (see below). The steps are: - - ... Address comments ... - ... git add / git remove ... - # Commit your updates locally - git commit -s - -If your changes are related to one initial commit, use the following subject: - - [Review] <Commit subject of the commit that is fixed by this one> - -...and give a quick description of what is being addressed if it is not -obvious. Note that you are expected to include your `Signed-off-by:` to those -fixup commits, too. You may use some other prefix than `[Review]`, it does not -matter much, but just make it clear you are updating a previous commit, and -which one it is. - -Once you are happy with your changes, and think all review comments have been -addressed (either by a followup commit or by replying to the comment on GitHub) -then you are ready to push your updates: - - git push - -The pull request is automatically updated with the new commit(s) and reviewers -are notified, too. - -### Finalizing your contribution - -Once you and reviewers have agreed on the patch set, which is when all the -people who have commented on the pull request have given their `Acked-by:` or -`Reviewed-by:`, you need to consolidate your commits: - -Use `git rebase -i` to squash the fixup commits (if any) into the initial -ones. For instance, suppose the `git log --oneline` for you contribution looks -as follows when the review process ends: - - <commit1> Do something - <commit2> Do something else - <commit3> [Review] Do something - <commit4> [Review] Do something - -Then you would do: - - git rebase -i <commit1>^ - # Edit the commit script so it looks like so: - pick <commit1> Do something - squash <commit3> [Review] Do something - squash <commit4> [Review] Do something - pick <commit2> Do something else - -Add the proper tags (`Acked-by: ...`, `Reviewed-by: ...`, `Tested-by: ...`) to -the commit message(s), as provided by the people who reviewed and/or tested the -patches. - -If you are not familiar with Git's interactive rebase feature, please read the -documentation at [Git Tools - Rewriting History]( -https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History). Sections -*Changing Multiple Commit Messages*, *Reordering Commits* and *Squashing -Commits* are relevant to the current discussion. - -Once `rebase -i` is done, you need to force-push (`-f`) to your GitHub branch -in order to update the pull request page. - - git push -f - -At this point, it is the project maintainer's job to apply your patches to the -master branch. diff --git a/documentation/globalplatform_api.md b/documentation/globalplatform_api.md deleted file mode 100644 index 2bce2ec7..00000000 --- a/documentation/globalplatform_api.md +++ /dev/null @@ -1,105 +0,0 @@ -GlobalPlatform API and OP-TEE -============================= - -Contents : - -1. Introduction -2. TEE Client API -3. TEE Internal API - -# 1. Introduction -[GlobalPlatform](http://www.globalplatform.org) works across industries to -identify, develop and publish specifications which facilitate the secure and -interoperable deployment and management of multiple embedded applications on -secure chip technology. OP-TEE has support for GlobalPlatform [TEE Client API -Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp) and -[TEE Internal Core API Specification v1.1](http://www.globalplatform.org/specificationsdevice.asp). - -# 2. TEE Client API -The TEE Client API describes and defines how a client running in a rich -operating environment (REE) should communicate with the TEE. To identify a -Trusted Application (TA) to be used, the client provides an -[UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier). All TA's -exposes one or several functions. Those functions corresponds to a so called -`commandID` which also is sent by the client. - -### TEE Contexts -The TEE Context is used for creating a logical connection between the client and -the TEE. The context must be initialized before the TEE Session can be -created. When the client has completed a jobs running in secure world, it should -finalize the context and thereby also releasing resources. - -### TEE Sessions -Sessions are used to create logical connections between a client and a specific -Trusted Application. When the session has been established the client have a -opened up the communication channel towards the specified Trusted Application -identified by the `UUID`. At this stage the client and the Trusted Application -can start to exchange data. - - -### TEE Client API example / usage -Below you will find the main functions as defined by GlobalPlatform and which -are used in the communication between the client and the TEE. - -#### TEE Functions -``` c -TEEC_Result TEEC_InitializeContext( - const char* name, - TEEC_Context* context) - -void TEEC_FinalizeContext( - TEEC_Context* context) - -TEEC_Result TEEC_OpenSession ( - TEEC_Context* context, - TEEC_Session* session, - const TEEC_UUID* destination, - uint32_t connectionMethod, - const void* connectionData, - TEEC_Operation* operation, - uint32_t* returnOrigin) - -void TEEC_CloseSession ( - TEEC_Session* session) - -TEEC_Result TEEC_InvokeCommand( - TEEC_Session* session, - uint32_t commandID, - TEEC_Operation* operation, - uint32_t* returnOrigin) -``` - -In principle the commands are called in this order: - - TEEC_InitializeContext(...) - TEEC_OpenSession(...) - TEEC_InvokeCommand(...) - TEEC_CloseSession(...) - TEEC_FinalizeContext(...) - -It is not uncommon that `TEEC_InvokeCommand` is called several times in row -when the session has been established. - -For a complete example, please see chapter **5.2 Example 1: Using the TEE -Client API** in the GlobalPlatform [TEE Client API -Specification v1.0](http://www.globalplatform.org/specificationsdevice.asp). - - -# 3. TEE Internal API -The Internal API is the API that is exposed to the Trusted Applications running -in the secure world. The TEE Internal API consists of four major parts: - -1. **Trusted Storage API for Data and Keys** -2. **Cryptographic Operations API** -3. **Time API** -4. **Arithmetical API** - -### Examples / usage -Calling the Internal Core API is done in the same way as described above using Client API. -The best place to find information how this should be done is in the -[TEE Internal Core API Specification -v1.1](http://www.globalplatform.org/specificationsdevice.asp) which contains a -lot of examples of how to call the various APIs. - -One can also have a look at the OP-TEE examples git repository -[optee_examples](https://github.com/linaro-swg/optee_examples) documentation. diff --git a/documentation/gprof.md b/documentation/gprof.md deleted file mode 100644 index 532900ab..00000000 --- a/documentation/gprof.md +++ /dev/null @@ -1,60 +0,0 @@ -# Profiling user Trusted Applications with `gprof` - -The configuration option `CFG_TA_GPROF_SUPPORT=y` enables OP-TEE to -collect profiling information from Trusted Applications running in user -mode and compiled with `-pg`. -Once collected, the profiling data are formated in the `gmon.out` format -and sent to `tee-supplicant` via RPC, so they can be saved to disk and -later processed and displayed by the standard `gprof` tool. - -## Usage - -- Build OP-TEE OS with `CFG_TA_GPROF_SUPPORT=y`. You may also set - `CFG_ULIBS_GPROF=y` to instrument the user TA libraries (libutee, libutils, - libmpa). -- Build user TAs with `-pg`, for instance using: `CFLAGS_ta_arm32=-pg` - or `CFLAGS_ta_arm64=-pg`. Note that instrumented TAs have a larger `.bss` - section. The memory overhead is 1.36 times the `.text` size for 32-bit TAs, - and 1.77 times for 64-bit ones (refer to the TA linker script for details: - `ta/arch/arm/ta.ld.S`). -- Run the application normally. When the last session exits, - `tee-supplicant` will write profiling data to - `/tmp/gmon-<ta_uuid>.out`. If the file already exists, a number is - appended, such as: `gmon-<ta_uuid>.1.out`. -- Run gprof on the TA ELF file and profiling output: - `gprof <ta_uuid>.elf gmon-<ta_uuid>.out` - -## Implementation - -Part of the profiling is implemented in libutee. Another part is done -in the TEE core by a pseudo-TA (`core/arch/arm/sta/gprof.c`). Two types -of data are collected: - - 1. Call graph information - - When TA source files are compiled with the -pg switch, the compiler -generates extra code into each function prologue to call the -instrumentation entry point (`__gnu_mcount_nc` or `_mcount` depending -on the architecture). Each time an instrumented function is called, -libutee records a pair of program counters (one is the caller and the -other one is the callee) as well as the number of times this specific -arc of the call graph has been invoked. - - 2. PC distribution over time - - When an instrumented TA starts, libutee calls the pseudo-TA to start -PC sampling for the current session. Sampling data are written into -the user-space buffer directly by the TEE core. - - Whenever the TA execution is interrupted, the TEE core records the -current program counter value and builds a histogram of program -locations (i.e., relative amount of time spent for each value of the -PC). This is later used by the gprof tool to derive the time -spent in each function. The sampling rate, which is assumed to be -roughly constant, is computed by keeping track of the time spent -executing user TA code and dividing the number of interrupts by the -total time. - -The profiling buffer into which call graph and sampling data are -recorded is allocated in the TA's `.bss` section. Some space is reserved -by the linker script, only when the TA is instrumented. diff --git a/documentation/images/benchmark/benchmark_design.png b/documentation/images/benchmark/benchmark_design.png Binary files differdeleted file mode 100644 index dfc79e1e..00000000 --- a/documentation/images/benchmark/benchmark_design.png +++ /dev/null diff --git a/documentation/images/benchmark/benchmark_design.xml b/documentation/images/benchmark/benchmark_design.xml deleted file mode 100644 index 1ece0b1b..00000000 --- a/documentation/images/benchmark/benchmark_design.xml +++ /dev/null @@ -1 +0,0 @@ -<mxfile userAgent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/59.0.3071.29 Chrome/59.0.3071.29 Safari/537.36" version="6.7.8" editor="www.draw.io" type="device"><diagram id="50283354-f32d-0512-eecf-47c7ab1951aa" name="Page-1">7V1bc6M6Ev41qTrzEBdCXOzHxJOc3do5O6mTs7V7nrYwyDY7GHkB57K/fiWQMLpgYxC2MzNJVQa3oMHqry/qbjQ3cL55+zULtuvfcISSG9uK3m7g5xvbnvo2+UsJ7xXBsUFFWGVxVJEahOf4f4gRLUbdxRHKhRMLjJMi3orEEKcpCguBFmQZfhVPW+JEvOs2WCGF8BwGiUr9ZxwVa/a1XGtP/wuKV2t+Z2CxkUUQfltleJey+93YcFn+VMObgPNi5+frIMKvDRJ8uIHzDOOiOtq8zVFCp5ZPW3XdY8to/dwZSosuF8Dqgpcg2SH+xOVzFe98LlAa3dEpJZ/CJMjzOLyB9+tikxACIIfoLS7+RY6tieeyj3/SoYlll5/TInuvxoHjccKfJcEClMEyTpI5TnBW3g9GLppGDqHnRYa/ocbI1F5Aj7JYZUEUEz6NsZkfWb5fX8WlBvgNn1AWb1CB6OkWe0yZVn11FCnY2M8mI+V4l4XsLJfhM8hWiJ3l1ZIkCoIwuUf2Tk553UOJI2ndQBGnZSgJivhFfIiAIXpVs6vv8IRj8ni2xZQPeIwP0z3bsUQW1cOzq5rYOMZoKjGqvrLCiBw0vvaeVEJPD0PHV2FHxPDMPuKsWOMVToPkYU+9L9UMRUx4GkSCBhytiQhGEYh07D+oKN6ZKQp2BSak/X2/YLxlHBVYPj5a5EcLvSVOC8YSQPa5cSW9bjZTVWA5DVEY6oGOAm9RKoExtPp6tHaGoSD3A0J2NbbGSwo2LYL0vf/uMB+4zcsJvCMngOn2rfzmfJwcrei/RJbhehNk3+gjbrecL3miinV1loIxEUGv67hAz9ugnKpX4tdEVClyj/zZok3ukjyXyCvl2cTDtH6iF5QV6O2wFFX5sAugqKSQaVLD1gBHY2xkXe4jUM8dQ2uZpnI3IroQV9Bb8iEJFii5r72uMOml3x2o2I+PfRT74c67P0lJB6hfR+PtOWa8AASjeQGv1UBE8YvWPhC1KW6DJF6llYFI0LJQrQPnkm+DtLOZ0XEJNtQmpIt8W362jJGSePHHw8O8YbeqZxWfn5DLiRjFmnnlTydr5tJfQmcT/7mcdSPGbCpiDfiOYs3qc5rWbGbAmvHwy7Q1s2Vz1tsezWbOvF+gUYcoHczlxUxWbaJq6cNOluY4I7tbBNzDZPmKyZonNGAjtLvtNolDMiE4vbyqjhB41ApzIPLgNNORx1TjKdqXrSlOqa5GQb4u5xyI89s2Z8q83z/S30Eqcp4loGOJonFhzyWgzEhWJHO+n0cVQ1cHPd3216db4oDJwd9++/r5PMuHa3S4dXB3zOECGVF9tBiAi8r8+yLVCP76fPX4DQk6adbNBIKdtvXJeSCsS6CeCGFHB+FGRqNFmI2VkUgaduOnHO0iTIb/uDty61GXIwaSK6OgzZfQZqtoq8PNtVgiMIA256S4R5+u3ydTbCWbYjYVf2ANpEr12mMqIIdCvRMqVovBGiGoUpcnD1/UZS7NohxSRxY/N8HBSIqKUeUii57kjg1s4igqF8o6/R9hUQIkIbmqeuqyoXJc20s51UXJwxfwI0327IyTPVMNn4lkjd80VJZoLn3FXHbN5Ojn/tTSDQdYs3ZT0c5QvOFCa6D77zjbBPScV5wl0fcMdHmZNFV9PhgJ6La6RnpG4S5DP8K8O8C72LzbyryDiboMaxYWqjj4LklwGBRUPkEalaq4inM6n0Rz4w3KC8rCtsI4C3dJQMmLHYlhs5zendYnnoTIWywEXKGs4ZEoUKl5z2aWZQYfQEAHcGwVH7pY3Ag+4DgO6ID/MeJ+tF0IgkROdUtcU5puqaKdwy0ZWBEZXvTsBWYBXxDZBOxDCLn36OMtiKCceLFnIovOSWbeLdjGyNyCCOoyjheFiyp3oUxx7SBwfNEGQ8/vBwLoHWFkEASqa79uEJzuHT4CdAA4kgfpnFCR16FyZsYgdAz0y14JdK4eHo4U3fmgJzwcER4AjGZZ3KmKhnMGhfSqMRvi5nPP69eAcnJDnBhjQqbRzRgTtnRZG48xPTVjaj7XJKXm1VzTlcu1V9RyXMhgaKtRVyFD3ULCRC06iRf/KAuzP3BN9rx9fOdIDUvq6jlQXOlVb7ZoV3o/gCJ7GmvtnEuR1S7i39GKZdpoZu3SCjdCntS1pVBakyj1NOpmohUPqjVGyXCG9STsbWP56gsthO5JHQwsPPb6x7+D3duHePnj0MtAY1hk25GTNZq+BWuqQsRI3wLU9Wue2JN/uEtGEvzBpPl32ZhSzzF3uVNPFbCuWOJ5w+XrzE6XL7MKVLbZavGL7bo3FJPkXtQs8KNP9LC0DiUelsEmTt6rq+piDJlqSBfQa5S8IFrDUEZEJpJBEceq56SDKS9vNoZf2cRpxhPis1F2S75vGKcr7Sny2ypM/sJwTKCZsjtYjacrB4ssSPMlYcrZp6g+ocRxeXv987/iLBKfrsk+ivNtErCZjdMkbnBeJjgoNHfcv+t8e0CY0vEnVYnhhHylbwRj6A2F5Kz5gPLXwPcgWHHMgD4C3xf0caaqo84jcy0eFAC3t9V21kbLqYUGLFunj32lb1KdjyhUq0rICHQmf01fSjO/2ZRF25HgVwfZo8OvXknVr8BAjb+HIwFQkxT9+SbVBd+k6tpieJSR3bG80yd3aqCS20EmYyyZ23YVmNl1VkC3/US5RQHPFNTbFLCLjG1PwUXfJat2ocLxrG/hWF72yozMZfY17ybbE/K5ufFA2bdTt/vQdh6psad6t8h6iQN63pbGOmFAb3PUr1ymq6dtgWrAP8kZQocHLc0MoWW3Y3CQf9K9aN5uao68PqhaFJv+DrL/ZyqxuaJxl9NBXfXQP99GMa4u2/TRvIRatBteppWMPt80q0MG9jxYc3lzXo0Rtx/YPDg7zMjgfhQGuoUuDraTQxKricDJtNqzSxOOGCgUXDYOcVzR/tXhxOm9S9ZhRgYhaQ+HpIK32rH338Bqb8AsYZVGex7b4tkP1egGXSjIGMqBSPduRylodcFoYDltmwRj9uui+yZdag1jCg4yI3Nw4Hf6gHD4UKZC7omtN9EY2hOrMDKIDQOhzrX4levHh6TyDuiJD3kHHnmnT4P40MDh51Z/Y9iooWt6GVy9u6olRiN2VftqV7VLk2u/Ivo8i92S/P0FpwmdHpyG6JOCxUtlzA7XcTqUEh7320kNKzdOW1IwDZPma0yaiVfheHPfz3pj13qjN/kd5bsNLaV/d4XHqZRU9FUgjlZ49EfakPajFR6vwxXVhqGteNi5Cikx6urTjrsi8nG/1351+v7/M4AP/wc=</diagram></mxfile>
\ No newline at end of file diff --git a/documentation/images/benchmark/benchmark_sequence.msc b/documentation/images/benchmark/benchmark_sequence.msc deleted file mode 100644 index df230c2b..00000000 --- a/documentation/images/benchmark/benchmark_sequence.msc +++ /dev/null @@ -1,46 +0,0 @@ -msc { - wordwraparcs=on, - hscale="0.95", - watermark="OP-TEE Benchmark"; - - tee [label="TEE", linecolor="darkgreen", textcolor="white", textbgcolor="darkgreen", arclinecolor="darkgreen", arctextcolor="darkgreen"], - kernel [label="Kernel", linecolor="maroon", textcolor="white", textbgcolor="maroon", arclinecolor="maroon", arctextcolor="maroon"], - libteec [label="libteec", linecolor="#3a5795", textcolor="white", textbgcolor="#3a5795", arclinecolor="#3a5795", arctextcolor="#3a5795"], - client [label="Benchmark CA/\nRegular CA", linecolor="#3a5795", textcolor="white", textbgcolor="#3a5795", arclinecolor="#3a5795", arctextcolor="#3a5795"]; - - ...[label="Benchmak CA is used to setup the benchmark environment (allocation/registering of the benchmark shared buffers) and then to fork itself into target tested application with eventual CLI arguments. Once the target test application ends, timestamp data are made available in the generated .ts file(s)."]; - ...; - ... [label="1. Allocate per-cpu timestamp ringbuffers"]; - client => kernel [label="Allocate shared mem for per-cpu timestamp buffers"]; - client << kernel; - - ... [label="2. Register timestamp buffers in the PTA"]; - client => libteec [label="TEEC_InvokeCommand(\nBENCHMARK_\nCMD_REGISTER_\nMEMREF)"]; - libteec => kernel; - kernel >> tee [label="register_benchmark_memref()"]; - ...; - tee => tee [label="Store benchmark buffer memref"]; - ...; - ...; - tee => kernel [label="Register memref in OP-TEE kmod via RPC"]; - kernel => kernel [label="Store benchmark buffer memref"]; - kernel >> tee; - ... [label="Jump back through all layers"]; - tee >> client; - - ... [label="3. Benchmarking is active now. Fork()/Exec() Regular CA, bypassed as a param to Benchmark CA"]; - - client => libteec [label="TEEC_InvokeCommand \n to regular TA"]; - ...; - libteec => libteec [label="Open session to Benchmark Pseudo TA"]; - libteec => kernel [label="TEEC_InvokeCommand(\nBENCHMARK_\nGET_MEMREF)"]; - ...; - kernel => tee [label="Invoke Pseudo TA"]; - ...; - tee => tee [label="get_benchmark_memref()"]; - tee => libteec [label="Return back paddr\n of timestamp buffer"]; - libteec => libteec [label="Mmap paddr into client VA space"]; - ... [label="4. Now we can put obtain timestamps also from libTEEC"]; - ...; - libteec => libteec [label="Resume TEEC_InvokeCommand of regular CA"]; -} diff --git a/documentation/images/benchmark/benchmark_sequence.png b/documentation/images/benchmark/benchmark_sequence.png Binary files differdeleted file mode 100644 index ce01c513..00000000 --- a/documentation/images/benchmark/benchmark_sequence.png +++ /dev/null diff --git a/documentation/images/green.svg b/documentation/images/green.svg deleted file mode 100644 index 578bab9d..00000000 --- a/documentation/images/green.svg +++ /dev/null @@ -1,12 +0,0 @@ -<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="20" height="20"> - <linearGradient id="b" x2="0" y2="100%"> - <stop offset="0" stop-color="#bbb" stop-opacity=".1"/> - <stop offset="1" stop-opacity=".1"/> - </linearGradient> - <clipPath id="a"> - <rect width="20" height="20" rx="3" fill="#fff"/> - </clipPath> - <g clip-path="url(#a)"> - <path fill="#4c1" d="M0 0h20v20H0z"/> - </g> -</svg> diff --git a/documentation/images/interrupt_handling/Makefile b/documentation/images/interrupt_handling/Makefile deleted file mode 100644 index 962cdee2..00000000 --- a/documentation/images/interrupt_handling/Makefile +++ /dev/null @@ -1,20 +0,0 @@ - -.PHONY: all -all: - -MSC_SRCS = tee_invoke.msc irq.msc fiq.msc irq_fiq.msc - -PNGS += $(MSC_SRCS:.msc=.png) - -# Disable all builtin rules -.SUFFIXES: -.SUFFIXES: .png .msc - -all: $(PNGS) - -%.png : %.msc - mscgen -T png $< - -.PHONY: clean -clean: - rm -f $(PNGS) diff --git a/documentation/images/interrupt_handling/fiq.msc b/documentation/images/interrupt_handling/fiq.msc deleted file mode 100644 index 5d1a2842..00000000 --- a/documentation/images/interrupt_handling/fiq.msc +++ /dev/null @@ -1,24 +0,0 @@ -msc { - hscale = "1.5", wordwraparcs = on; - - a [label="Normal world"], b [label="Secure Monitor"], - c [label="Trusted OS entry"], d [label="Trusted OS"]; - - - ||| ; - --- [ label = "Running in non-secure world (SCR_NS set)" ]; - ... ; - --- [ label = "IRQ and FIQ masked,\nFIQ received" ]; - b=>b [ label = "Save non-secure context" ]; - b=>b [ label = "Restore secure context" ]; - b>>c [ label = "eret: FIQ" ]; - --- [ label = "FIQ unmasked" ]; - d=>d [ label = "process received FIQ" ]; - --- [ label = "FIQ masked" ]; - c=>b [ label = "smc: return" ]; - b=>b [ label = "Save secure context" ]; - b=>b [ label = "Restore non-secure context" ]; - b>>a [ label = "eret: return to Normal world" ]; - --- [ label = "IRQ and FIQ unmasked" ]; - ... ; -} diff --git a/documentation/images/interrupt_handling/fiq.png b/documentation/images/interrupt_handling/fiq.png Binary files differdeleted file mode 100644 index 0037c1b1..00000000 --- a/documentation/images/interrupt_handling/fiq.png +++ /dev/null diff --git a/documentation/images/interrupt_handling/irq.msc b/documentation/images/interrupt_handling/irq.msc deleted file mode 100644 index 62657ccf..00000000 --- a/documentation/images/interrupt_handling/irq.msc +++ /dev/null @@ -1,30 +0,0 @@ -msc { - hscale = "1.5", wordwraparcs = on; - - a [label="Normal world"], b [label="Secure Monitor"], - c [label="Trusted OS entry"], d [label="Trusted OS"]; - - - --- [ label = "IRQ and FIQ unmasked" ]; - d=>d [ label = "process" ]; - --- [ label = "IRQ and FIQ masked,\nIRQ received" ]; - d=>d [ label = "suspend thread" ]; - d=>c [ label = "forward IRQ" ]; - c=>b [ label = "smc: forward IRQ" ]; - b=>b [ label = "Save secure context" ]; - b=>b [ label = "Restore non-secure context" ]; - --- [ label = "IRQ and FIQ unmasked" ]; - b>>a [ label = "eret: IRQ forwarded" ]; - --- [ label = "FIQ unmasked, IRQ received" ]; - a=>a [ label = "process IRQ" ]; - --- [ label = "IRQ and FIQ unmasked" ]; - a=>b [ label = "smc: return from IRQ" ]; - --- [ label = "IRQ and FIQ masked" ]; - b=>b [ label = "Save non-secure context" ]; - b=>b [ label = "Restore secure context" ]; - b>>c [ label = "eret: return from IRQ" ]; - c=>c [ label = "find thread" ]; - c>>d [ label = "resume execution"]; - --- [ label = "IRQ and FIQ unmasked" ]; - d=>d [ label = "process" ]; -} diff --git a/documentation/images/interrupt_handling/irq.png b/documentation/images/interrupt_handling/irq.png Binary files differdeleted file mode 100644 index 293b3039..00000000 --- a/documentation/images/interrupt_handling/irq.png +++ /dev/null diff --git a/documentation/images/interrupt_handling/irq_fiq.msc b/documentation/images/interrupt_handling/irq_fiq.msc deleted file mode 100644 index 50983603..00000000 --- a/documentation/images/interrupt_handling/irq_fiq.msc +++ /dev/null @@ -1,43 +0,0 @@ -msc { - hscale = "1.5", wordwraparcs = on; - - a [label="Normal world"], b [label="Secure Monitor"], - c [label="Trusted OS entry"], d [label="Trusted OS"]; - - - --- [ label = "IRQ and FIQ unmasked" ]; - d=>d [ label = "process" ]; - --- [ label = "IRQ and FIQ masked,\nIRQ received" ]; - d=>d [ label = "suspend thread" ]; - d=>c [ label = "forward IRQ" ]; - c=>b [ label = "smc: forward IRQ" ]; - b=>b [ label = "Save secure context" ]; - b=>b [ label = "Restore non-secure context" ]; - --- [ label = "IRQ and FIQ unmasked" ]; - b>>a [ label = "eret: IRQ forwarded" ]; - --- [ label = "FIQ unmasked, IRQ received" ]; - a=>a [ label = "process IRQ" ]; - --- [ label = "IRQ and FIQ masked,\nFIQ received" ]; - b=>b [ label = "Save non-secure context" ]; - b=>b [ label = "Restore secure context" ]; - b>>c [ label = "eret: FIQ" ]; - --- [ label = "FIQ unmasked" ]; - d=>d [ label = "process received FIQ" ]; - --- [ label = "FIQ masked" ]; - c=>b [ label = "smc: return" ]; - b=>b [ label = "Save secure context" ]; - b=>b [ label = "Restore non-secure context" ]; - b>>a [ label = "eret: return to Normal world" ]; - --- [ label = "FIQ unmasked,\nIRQ still being processed" ]; - a=>a [ label = "process IRQ" ]; - a=>b [ label = "smc: return from IRQ" ]; - --- [ label = "IRQ and FIQ masked" ]; - b=>b [ label = "Save non-secure context" ]; - b=>b [ label = "Restore secure context" ]; - b>>c [ label = "eret: return from IRQ" ]; - c=>c [ label = "find thread" ]; - c>>d [ label = "resume execution"]; - --- [ label = "IRQ and FIQ unmasked" ]; - d=>d [ label = "process" ]; -} - diff --git a/documentation/images/interrupt_handling/irq_fiq.png b/documentation/images/interrupt_handling/irq_fiq.png Binary files differdeleted file mode 100644 index e1359ae6..00000000 --- a/documentation/images/interrupt_handling/irq_fiq.png +++ /dev/null diff --git a/documentation/images/interrupt_handling/tee_invoke.msc b/documentation/images/interrupt_handling/tee_invoke.msc deleted file mode 100644 index 6ea699d6..00000000 --- a/documentation/images/interrupt_handling/tee_invoke.msc +++ /dev/null @@ -1,25 +0,0 @@ -msc { - hscale = "1.5", wordwraparcs = on; - - a [label="Normal world"], b [label="Secure Monitor"], - c [label="Trusted OS entry"], d [label="Trusted OS"]; - - - --- [ label = "IRQ and FIQ unmasked" ]; - a=>b [ label = "smc: TEE_FUNC_INVOKE" ]; - --- [ label = "IRQ and FIQ masked" ]; - b=>b [ label = "Save non-secure context" ]; - b=>b [ label = "Restore secure context" ]; - b>>c [ label = "eret: TEE_FUNC_INVOKE" ]; - c=>c [ label = "assign thread" ]; - c=>d [ label = "TEE_FUNC_INVOKE" ]; - --- [ label = "IRQ and FIQ unmasked" ]; - d=>d [ label = "process" ]; - --- [ label = "IRQ and FIQ masked" ]; - d>>c [ label = "SMC_CALL_RETURN" ]; - c=>b [ label = "smc: SMC_CALL_RETURN" ]; - b=>b [ label = "Save secure context" ]; - b=>b [ label = "Restore non-secure context" ]; - --- [ label = "IRQ and FIQ unmasked" ]; - b>>a [ label = "eret: return" ]; -} diff --git a/documentation/images/interrupt_handling/tee_invoke.png b/documentation/images/interrupt_handling/tee_invoke.png Binary files differdeleted file mode 100644 index bbc592b4..00000000 --- a/documentation/images/interrupt_handling/tee_invoke.png +++ /dev/null diff --git a/documentation/images/orange.svg b/documentation/images/orange.svg deleted file mode 100644 index b7edca5e..00000000 --- a/documentation/images/orange.svg +++ /dev/null @@ -1,12 +0,0 @@ -<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="20" height="20"> - <linearGradient id="b" x2="0" y2="100%"> - <stop offset="0" stop-color="#bbb" stop-opacity=".1"/> - <stop offset="1" stop-opacity=".1"/> - </linearGradient> - <clipPath id="a"> - <rect width="20" height="20" rx="3" fill="#fff"/> - </clipPath> - <g clip-path="url(#a)"> - <path fill="#fe7d37" d="M0 0h20v20H0z"/> - </g> -</svg> diff --git a/documentation/images/red.svg b/documentation/images/red.svg deleted file mode 100644 index cb19dd02..00000000 --- a/documentation/images/red.svg +++ /dev/null @@ -1,12 +0,0 @@ -<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="20" height="20"> - <linearGradient id="b" x2="0" y2="100%"> - <stop offset="0" stop-color="#bbb" stop-opacity=".1"/> - <stop offset="1" stop-opacity=".1"/> - </linearGradient> - <clipPath id="a"> - <rect width="20" height="20" rx="3" fill="#fff"/> - </clipPath> - <g clip-path="url(#a)"> - <path fill="#e05d44" d="M0 0h20v20H0z"/> - </g> -</svg> diff --git a/documentation/images/secure_storage/block_data_encryption.odg b/documentation/images/secure_storage/block_data_encryption.odg Binary files differdeleted file mode 100644 index 53a3b6f4..00000000 --- a/documentation/images/secure_storage/block_data_encryption.odg +++ /dev/null diff --git a/documentation/images/secure_storage/block_data_encryption.png b/documentation/images/secure_storage/block_data_encryption.png Binary files differdeleted file mode 100644 index b2ce8495..00000000 --- a/documentation/images/secure_storage/block_data_encryption.png +++ /dev/null diff --git a/documentation/images/secure_storage/meta_data_encryption.odg b/documentation/images/secure_storage/meta_data_encryption.odg Binary files differdeleted file mode 100644 index 5ccb9b3d..00000000 --- a/documentation/images/secure_storage/meta_data_encryption.odg +++ /dev/null diff --git a/documentation/images/secure_storage/meta_data_encryption.png b/documentation/images/secure_storage/meta_data_encryption.png Binary files differdeleted file mode 100644 index 5a50d735..00000000 --- a/documentation/images/secure_storage/meta_data_encryption.png +++ /dev/null diff --git a/documentation/images/secure_storage/secure_storage_system_architecture.odg b/documentation/images/secure_storage/secure_storage_system_architecture.odg Binary files differdeleted file mode 100644 index 84621090..00000000 --- a/documentation/images/secure_storage/secure_storage_system_architecture.odg +++ /dev/null diff --git a/documentation/images/secure_storage/secure_storage_system_architecture.png b/documentation/images/secure_storage/secure_storage_system_architecture.png Binary files differdeleted file mode 100644 index 188ec97e..00000000 --- a/documentation/images/secure_storage/secure_storage_system_architecture.png +++ /dev/null diff --git a/documentation/images/xlat_table.dot b/documentation/images/xlat_table.dot deleted file mode 100644 index 316cd6d9..00000000 --- a/documentation/images/xlat_table.dot +++ /dev/null @@ -1,29 +0,0 @@ -digraph g { - graph [ - rankdir = "LR" - ]; - node [ - fontsize = "16" - shape = "ellipse" - ]; - edge [ - ]; - "node_ttb" [ - label = "<f0> TTBR0 | <f1> TTBR1" - shape = "record" - ]; - "node_large_l1" [ - label = "<f0> Large L1\nSpans 4 GiB" - shape = "record" - ]; - "node_small_l1" [ - label = "Small L1\nSpans 32 MiB\nper entry | <f0> 0 | <f1> 1 | ... | <fn> n" - shape = "record" - ]; - - "node_ttb":f0 -> "node_small_l1":f0 [ label = "Thread 0 ctx active" ]; - "node_ttb":f0 -> "node_small_l1":f1 [ label = "Thread 1 ctx active" ]; - "node_ttb":f0 -> "node_small_l1":fn [ label = "Thread n ctx active" ]; - "node_ttb":f0 -> "node_large_l1" [ label="No active ctx" ]; - "node_ttb":f1 -> "node_large_l1"; -} diff --git a/documentation/images/xlat_table.png b/documentation/images/xlat_table.png Binary files differdeleted file mode 100644 index b1198a2b..00000000 --- a/documentation/images/xlat_table.png +++ /dev/null diff --git a/documentation/interrupt_handling.md b/documentation/interrupt_handling.md deleted file mode 100644 index 8c1d6cf2..00000000 --- a/documentation/interrupt_handling.md +++ /dev/null @@ -1,279 +0,0 @@ -Exceptions, Interrupts and World Contexts -========================================= - -This document describes how optee_os handles switches of -world execution context based on SMC exceptions and interrupt notifications -Interrupt notifications are IRQ/FIQ exceptions which may also imply switching -of world execution context: normal world to secure world, or secure world to -normal world. - -## Content - -1. [Context Switches and Exceptions](#1-context-switches-and-exceptions) -2. [Normal World Invokes the optee_os Through a SMC](#2-normal-world-invokes-the-optee_os-through-a-smc) -3. [Deliver a Non-Secure Interrupt to the Normal World](#3-deliver-a-non-secure-interrupt-to-the-normal-world) -4. [Deliver a Secure Interrupt to the Secure World](#4-deliver-a-secure-interrupt-to-the-secure-world) -5. [Trusted Thread Scheduling](#5-trusted-thread-scheduling) - -# 1. Context Switches and Exceptions - -## 1.1. Usecases of world context switch - -This section lists all the cases where optee_os is involved in world context -switches. Optee_os executes in the secure world. World switch are done by the -cores secure monitor level/mode, referred below as the Monitor. - -When the normal world invokes the secure world, the normal world executes -a SMC instruction. The SMC exception is always trapped by the Monitor. If -the related service targets the trusted OS, the Monitor will switch to optee_os -world execution. When the secure world returns to the normal world, optee_os -executes a SMC that is caught by the Monitor which switches back to the normal -world. - -When a secure interrupt is signaled by the ARM GIC, it shall reach the -optee_os interrupt exception vector. If the secure world is executing, -optee_os will handle straight the interrupt from its exception vector. If the -normal world is executing when the secure interrupt raises, the Monitor -vector must handle the exception and invoke the optee_os to serve the -interrupt. - -When a non-secure interrupt is signaled by the ARM GIC, it shall reach the -normal world interrupt exception vector. If the normal world is -executing, it will handle straight the exception from its exception vector. If -the secure world is executing when the non-secure interrupt raises, -optee_os will temporarily return back to normal world via the Monitor to let -normal world serve the interrupt. - -## 1.2. Core Exception Vectors - -Monitor vector is VBAR_EL3 in AArch64 and MVBAR in ARMv7/AArch32. Monitor -can be reached while normal world or secure world is executing. The executing -secure state is known to the Monitor through the SCR_NS. - -Monitor can be reached from a SMC exception, an IRQ or FIQ exception -(so-called interrupts) and from asynchronous aborts. Obviously monitor -aborts (data, prefetch, undef) are local to the Monitor execution. - -The Monitor can be external to optee_os (case CFG_WITH_ARM_TRUSTED_FW=y). If -not, optee_os provides a local secure monitor `core/arch/arm/sm`. ARMv7 -platforms should use the optee_os secure monitor. ARMv8 platforms are likely -to rely on an [ARM Trusted Firmware](https://github.com/ARM-software/arm-trusted-firmware) - -When executing outside the Monitor, the system is executing either in the -normal world (SCR_NS=1) or in the secure world (SCR_NS=0). Each world owns -its own exception vector table (state vector): -* VBAR_EL2 or VBAR_EL1 non-secure or VBAR_EL1 secure for AArch64. -* HVBAR or VBAR non-secure or VBAR secure for ARMv7 and AArch32. - -All SMC exceptions are trapped in the Monitor vector. - -IRQ/FIQ exceptions can be trapped either in the Monitor vector or in the -state vector of the executing world. - -When the normal world is executing, the system is configured to route: -- secure interrupts to the Monitor that will forward to optee_os -- non-secure interrupts to the executing world exception vector. - -When the secure world is executing, the system is configured to route: -- secure and non-secure interrupts to the executing optee_os exception - vector. optee_os shall forward the non-secure interrupts to the normal - world. - -Optee_os non-secure interrupts are always trapped in the state vector -of the executing world. This is reflected by a static value of SCR_(IRQ|FIQ). - -## 1.3. Optee_os Native and Foreign Interrupts - -Two types of interrupt are defined in optee_os: -* Native interrupt - The interrupt handled by optee_os - (for example: secure interrupt) -* Foreign interrupt - The interrupt not handled by optee_os - (for example: non-secure interrupt which is handled by normal world) - -For ARM GICv2 mode, native interrupt is sent as FIQ and foreign interrupt is -sent as IRQ. - -For ARM GICv3 mode, foreign interrupt is sent as FIQ which could be handled -by either secure world (aarch32 Monitor mode or aarch64 EL3) or normal world. -ARM GICv3 mode can be enabled by setting `CFG_ARM_GICV3=y`. - -For clarity, this document mainly chooses the GICv2 convention and refers the -IRQ as optee_os foreign interrupts, and FIQ as optee_os native interrupts. - -Native interrupts must be securely routed to optee_os. Foreign interrupts, -when trapped during secure world execution might need to be efficiently routed -to the normal world. - -# 2. Normal World Invokes the optee_os Through a SMC - -## 2.1. Entering the Secure Monitor -The monitor manages all entry and exit of secure world. To enter secure -world from normal world the monitor saves the state of normal world -(general purpose registers and system registers which are not banked) and -restores the previous state of secure world. Then a return from exception -is performed and the restored secure state is resumed. Exit from secure -world to normal world is the reverse. - -Some general purpose registers are not saved and restored on entry and -exit, those are used to pass parameters between secure and normal world -(see ARM_DEN0028A_SMC_Calling_Convention for details). - -## 2.2. Entry and exit of Trusted OS -On entry and exit of Trusted OS each CPU is uses a separate entry stack and -runs with IRQ and FIQ blocked. - -SMCs are categorised in two flavor: fast and standard. - -For fast SMCs, optee_os will execute on the entry stack with IRQ/FIQ blocked -until the execution returns to normal world. - -For standard SMCs, optee_os will at some point execute the requested service -with interrupts unblocked. In order to handle interrupts, mainly forwarding of -foreign interrupts, optee_os assigns a trusted thread (core/arch/arm/thread.c) -to the SMC request. The trusted thread stores the execution context of the -requested service. This context can be suspended and resumed as the requested -service -executes and is interrupted. The trusted thread is released only once the -service execution returns with a completion status. - -For standard SMCs, optee_os allocates or resumes a trusted thread then unblock -the IRQ/FIQ lines. When the optee_os needs to invoke the normal world from -a foreign interrupt or a remote service call, optee_os blocks IRQ/FIQ and -suspends the trusted thread. When suspeding, optee_os gets back to the entry -stack. - -Both fast and standard SMC end on the entry stack with IRQ/FIQ blocked and -optee_os invokes the Monitor through a SMC to return to the normal world. - - - - -# 3. Deliver a Non-Secure Interrupt to the Normal World - -This section uses the ARM GICv1/v2 conventions: IRQ signals non-secure interrupts -while FIQ signals secure interrupts. On a GICv3 configuration, one should -exchange IRQ and FIQ in this section. - -## 3.1. Forward a Foreign Interrupt from Secure World to Normal World - -When an IRQ is received in secure world as an IRQ exception then secure world: - -1. Saves trusted thread context (entire state of all processor modes for ARMv7) -2. Blocks (masks) all interrupts (IRQ and FIQ) -3. Switches to entry stack -4. Issues an SMC with a value to indicates to normal world that an IRQ has - been delivered and last SMC call should be continued - -The monitor restores normal world context with a return code indicating -that an IRQ is about to be delivered. Normal world issues a new SMC -indicating that it should continue last SMC. - -The monitor restores secure world context which locates the previously -saved context and checks that it is a return from IRQ that is requested -before restoring the context and lets the secure world IRQ handler return -from exception where the execution would be resumed. - -Note that the monitor itself does not know/care that it has just forwarded -an IRQ to normal world. The bookkeeping is done in the trusted thread handling in -Trusted OS. Normal world is responsible to decide when the secure world -thread should resume execution. See some details in section -[Trusted Thread Scheduling](#5-trusted-thread-scheduling). - - - -## 3.2. Deliver a non-secure interrupt to normal world when SCR_NS is set -Since SCR_IRQ is cleared, an IRQ will be delivered using the state vector (VBAR) -in the normal world. The IRQ is received as any other exception by normal world, -the monitor and the Trusted OS are not involved at all. - -# 4. Deliver a Secure Interrupt to the Secure World - -This section uses the ARM GICv1/v2 conventions: FIQ signals secure interrupts -while IRQ signals non-secure interrupts. On a GICv3 configuration, one should -exchange IRQ and FIQ in this section. - -A FIQ can be received during two different states, either in normal -world (SCR_NS is set) or in secure world (SCR_NS is cleared). When the -secure monitor is active (ARMv8 EL3 or ARMv7 Monitor mode) FIQ is masked. -FIQ reception in the two different states is described below. - -## 4.1. Deliver FIQ to secure world when SCR_NS is set - -When the monitor gets an FIQ exception it: - -1. Saves normal world context and restores secure world context from last - secure world exit (which will have IRQ and FIQ blocked) -2. Clears SCR_FIQ when clearing SCR_NS -3. Sets “FIQ” as parameter to secure world entry -4. Does a return from exception into secure context -5. Secure world unmasks FIQs because of the “FIQ” parameter -6. FIQ is received as in exception using the state vector -7. The state vector handle returns from exception in secure world -8. Secure world issues an SMC to return to normal world -9. Monitor saves secure world context and restores normal world context -10. Does a return from exception into restored context - - - - - -## 4.2. Deliver FIQ to secure world when SCR_NS is cleared - -Since SCR_FIQ is cleared when SCR_NS is cleared a FIQ will be delivered -using the state vector (VBAR) in secure world. The FIQ is received as any -other exception by Trusted OS, the monitor is not involved at all. - -# 5. Trusted Thread Scheduling - -## 5.1. Trusted Thread for Standard Services - -OP-TEE standard services are carried through standard SMC. Execution of these -services can be interrupted by foreign interrupts. To suspend and restore the -service execution, optee_os assigns a trusted thread at standard SMCs entry. - -The trusted thread -terminates when optee_os returns to the normal world with a service completion -status. - -A trusted thread execution can be interrupted by a native interrupt. In this case -the native interrupt is handled by the interrupt exception handlers and once -served, optee_os returns to the execution trusted thread. - -A trusted thread execution can be interrupted by a foreign interrupt. In this -case, optee_os suspends the trusted thread and invokes the normal world through the -Monitor (optee_os so-called RPC services). The trusted threads will resume -only once normal world invokes the optee_os with the RPC service status. - -A trusted thread execution can lead optee_os to invoke a service in normal -world: access a file, get the REE current time, etc. The trusted thread is -suspended/resumed during remote service execution. - -## 5.2. Scheduling Considerations - -When a trusted thread is interrupted by a foreign interrupt and when optee_os -invokes a normal world service, the normal world gets the opportunity to -reschedule the running applications. The trusted thread will resume only -once the client application is scheduled back. Thus, a trusted thread execution -follows the scheduling of the normal world caller context. - -Optee_os does not implement any thread scheduling. Each trusted thread is expected -to track a service that is invoked from the normal world and should return to -it with an execution status. - -The OP-TEE Linux driver (as implemented in drivers/tee/optee since Linux kernel -4.12) is designed so that the Linux thread invoking OP-TEE gets -assigned a trusted thread on TEE side. The execution of the trusted thread is -tied to the execution of the caller Linux thread which is under the -Linux kernel scheduling decision. This means trusted threads are scheduled by the -Linux kernel. - -## 5.3. Trusted Thread Constraints -optee_os handles a static number of trusted threads, `CFG_NUM_THREAD`. - -Trusted threads are only expensive on memory constrained system, mainly regarding -the execution stack size. - -On SMP systems, optee_os can execute several trusted threads in parallel if the -normal world supports scheduling of processes. Even on UP systems, supporting -several trusted threads in optee_os helps normal world scheduler to be -efficient. diff --git a/documentation/optee_design.md b/documentation/optee_design.md deleted file mode 100644 index 02f0e92f..00000000 --- a/documentation/optee_design.md +++ /dev/null @@ -1,890 +0,0 @@ -OP-TEE design -======================== - -# Contents - -1. [Introduction](#1-introduction) -2. [Platform Initialization](#2-platform-initialization) -3. [Secure Monitor Calls - SMC](#3-secure-monitor-calls---smc) -4. [Thread handling](#4-thread-handling) -5. [MMU](#5-mmu) -6. [Stacks](#6-stacks) -7. [Shared Memory](#7-shared-memory) -8. [Pager](#8-pager) -9. [Memory Objects](#9-memory-objects) -10. [Cryptographic abstraction layer](#10-cryptographic-abstraction-layer) -11. [libutee](#11-libutee) -12. [Trusted Applications](#12-trusted-applications) -13. [Device Tree support](#13-device-tree-support) - -# 1. Introduction -OP-TEE is a so called Trusted Execution Environment, in short a TEE, for ARM -based chips supporting TrustZone technology. OP-TEE consists of three -components. - -+ [OP-TEE Client], which is the client API running in normal world user space. -+ [OP-TEE Linux Kernel driver], which is the driver that handles the - communication between normal world user space and secure world. -+ [OP-TEE Trusted OS], which is the Trusted OS running in secure world. - -OP-TEE was designed with scalability and portability in mind and as of now it -has been ported to quite a few different platforms, both ARMv7-A and ARMv8-A -from different vendors. For a full list, please see [Platforms Supported]. - -OP-TEE OS is made of 2 main components: the OP-TEE core and a collection of -libraries designed for being used by Trusted Applications. While OP-TEE core -executes in the ARM CPU privileged level (also referred to as 'kernel land'), -the Trusted Applications execute in the non-privileged level (also referred to as -the 'userland'). The static libraries provided by the OP-TEE OS enable Trusted -Applications to call secure services executing at a more privileged level. - -# 2. Platform initialization -TBD - -# 3. Secure Monitor Calls - SMC -## 3.1 SMC handling -TBD - -## 3.2 SMC Interface -The OP-TEE SMC interface is defined in two levels using [optee_smc.h] and -[optee_msg.h]. The former file defines SMC identifiers and what is passed in the -registers for each SMC. The latter file defines the OP-TEE Message protocol -which is not restricted to only SMC even if that currently is the only option -available. - -## 3.3 Communication using SMC Interface -The main structure used for the SMC communication is defined in [struct -optee_msg_arg]. If we are looking into the source code, we could see that -communication mainly is achieved using `optee_msg_arg` and `thread_smc_args`, -where `optee_msg_arg` could be seen as the main structure. What will happen is -that the [OP-TEE Linux Kernel driver] will get the parameters either from -[OP-TEE Client] or directly from an internal service in the Linux kernel. The -TEE driver will populate the struct `optee_msg_arg` with the parameters plus -some additional bookkeeping information. Parameters for the SMC are passed in -registers 1 to 7, register 0 holds the SMC id which among other things tells -whether it is a standard or a fast call. - -# 4. Thread handling -The OP-TEE core uses a couple of threads to be able to support running jobs in -parallel (not fully enabled!). There are handlers for different purposes. In -[thread.c] you will find a function called `thread_init_primary` which assigns -`init_handlers` (functions) that should be called when OP-TEE core receives -standard or fast calls, FIQ and PSCI calls. There are default handlers for these -services, but the platform can decide if they want to implement their own -platform specific handlers instead. - -## Synchronization -OP-TEE has three primitives for synchronization of threads and CPUs: -spin-lock, mutex, and condvar. - -### Spin-lock -A spin-lock is represented as an `unsigned int`. This is the most primitive -lock. Interrupts should be disabled before attempting to take a spin-lock -and should remain disabled until the lock is released. A spin-lock is -initialized with `SPINLOCK_UNLOCK`. - -| Function | Purpose | -|----------|---------| -| `cpu_spin_lock()` | Locks a spin-lock | -| `cpu_spin_trylock()` | Locks a spin-lock if unlocked and returns `0` else the spin-lock is unchanged and the function returns `!0`| -| `cpu_spin_unlock()` | Unlocks a spin-lock | - -### Mutex -A mutex is represented by `struct mutex`. A mutex can be locked and -unlocked with interrupts enabled or disabled, but only from a normal -thread. A mutex cannot be used in an interrupt handler, abort handler or -before a thread has been selected for the CPU. A mutex is initialized with -either `MUTEX_INITIALIZER` or `mutex_init()`. - -| Function | Purpose | -|----------|---------| -|`mutex_lock()` | Locks a mutex. If the mutex is unlocked this is a fast operation, else the function issues an RPC to wait in normal world. | -| `mutex_unlock()` | Unlocks a mutex. If there is no waiters this is a fast operation, else the function issues an RPC to wake up a waiter in normal world. | -| `mutex_trylock()` | Locks a mutex if unlocked and returns `true` else the mutex is unchanged and the function returns `false`. | -| `mutex_destroy()` | Asserts that the mutex is unlocked and there is no waiters, after this the memory used by the mutex can be freed. | - -When a mutex is locked it is owned by the thread calling `mutex_lock()` or -`mutex_trylock()`, the mutex may only be unlocked by the thread owning the -mutex. A thread should not exit to TA user space when holding a mutex. - -### Condvar -A condvar is represented by `struct condvar`. A condvar is similar to a -pthread_condvar_t in the pthreads standard, only less advanced. Condition -variables are used to wait for some condition to be fulfilled and are -always used together a mutex. Once a condition variable has been used -together with a certain mutex, it must only be used with that mutex until -destroyed. A condvar is initialized with `CONDVAR_INITIALIZER` or -`condvar_init()`. - -| Function | Purpose | -|----------|---------| -| `condvar_wait()` | Atomically unlocks the supplied mutex and waits in normal world via an RPC for the condition variable to be signaled, when the function returns the mutex is locked again. | -| `condvar_signal()` | Wakes up one waiter of the condition variable (waiting in `condvar_wait()`) | -| `condvar_broadcast()` | Wake up all waiters of the condition variable. | - -The caller of `condvar_signal()` or `condvar_broadcast()` should hold the -mutex associated with the condition variable to guarantee that a waiter -does not miss the signal. - -# 5. MMU -## Translation tables -OP-TEE uses several L1 translation tables, one large spanning 4 GiB and two -or more small tables spanning 32 MiB. The large translation table handles -kernel mode mapping and matches all addresses not covered by the small -translation tables. The small translation tables are assigned per thread -and covers the mapping of the virtual memory space for one TA context. - -Memory space between small and large translation table is configured by -TTBRC. TTBR1 always points to the large translation table. TTBR0 points to -the a small translation table when user mapping is active and to the large -translation table when no user mapping is currently active. - -The translation tables has certain alignment constraints, the alignment (of -the physical address) has to be the same as the size of the translation -table. The translation tables are statically allocated to avoid fragmentation of -memory due to the alignment constraints. - -Each thread has one small L1 translation table of its own. Each TA context -has a compact representation of its L1 translation table. The compact -representation is used to initialize the thread specific L1 translation -table when the TA context is activated. - - - -## Translation tables and switching to user mode -This section only applies with `CFG_WITH_LPAE=n` and -`CFG_CORE_UNMAP_CORE_AT_EL0=y`. - -When switching to user mode only a minimal kernel mode mapping is kept. -This is achieved by selecting a zeroed out big L1 translation in TTBR1 when -transitioning to user mode. When returning back to kernel mode the original -L1 translation table is restored in TTBR1. - -## Translation tables and switching to normal world -When switching to normal world either via a foreign interrupt or RPC there -is a chance that secure world will resume execution on a different CPU. -This means that the new CPU need to be configured with the context of the -currently active TA. This is solved by always setting the TA context in -the CPU when resuming execution. Here is room for improvements since it is -more likely than not that it is the same CPU that resumes execution in -secure world. - -# 6. Stacks -Different stacks are used during different stages. The stacks are: -- Secure monitor stack (128 bytes), bound to the CPU. Only available if - OP-TEE is compiled with a secure monitor always the case if the target is - ARMv7-A but never for ARMv8-A. -- Temp stack (small ~1KB), bound to the CPU. Used when transitioning from - one state to another. Interrupts are always disabled when using this - stack, aborts are fatal when using the temp stack. -- Abort stack (medium ~2KB), bound to the CPU. Used when trapping a data - or pre-fetch abort. Aborts from user space are never fatal the TA is only - killed. Aborts from kernel mode are used by the pager to do the demand - paging, if pager is disabled all kernel mode aborts are fatal. -- Thread stack (large ~8KB), not bound to the CPU instead used by the current - thread/task. Interrupts are usually enabled when using this stack. - -*Notes for ARMv7/AArch32:* - -| Stack | Comment | -|--------|---------| -| Temp | Assigned to `SP_SVC` during entry/exit, always assigned to `SP_IRQ` and `SP_FIQ` | -| Abort | Always assigned to `SP_ABT` | -| Thread | Assigned to `SP_SVC` while a thread is active | - -*Notes for AArch64:* -There are only two stack pointers, `SP_EL1` and `SP_EL0`, available for OP-TEE -in AArch64. When an exception is received stack pointer is always `SP_EL1` which -is used temporarily while assigning an appropriate stack pointer for `SP_EL0`. -**`SP_EL1` is always assigned the value of `thread_core_local[cpu_id]`.** This -structure has some spare space for temporary storage of registers and also keeps -the relevant stack pointers. In general when we talk about assigning a stack -pointer to the CPU below we mean `SP_EL0`. - -## Boot -During early boot the CPU is configured with the temp stack which is used until -OP-TEE exits to normal world the first time. - -*Notes for AArch64:* -`SPSEL` is always `0` on entry/exit to have `SP_EL0` acting as stack pointer. - -## Normal entry -Each time OP-TEE is entered from normal world the temp stack is used as the -initial stack. For fast calls this is the only stack used. For normal calls an -empty thread slot is selected and the CPU switches to that stack. - -## Normal exit -Normal exit occurs when a thread has finished its task and the thread is freed. -When the main thread function, tee_entry_std(), returns interrupts are disabled -and the CPU switches to the temp stack instead. The thread is freed and OP-TEE -exits to normal world. - -## RPC exit -RPC exit occurs when OP-TEE need some service from normal world. RPC can -currently only be performed with a thread is in running state. RPC is initiated -with a call to thread_rpc() which saves the state in a way that when the thread -is restored it will continue at the next instruction as if this function did a -normal return. CPU switches to use the temp stack before returning to normal -world. - -## Foreign interrupt exit -Foreign interrupt exit occurs when OP-TEE receives a foreign interrupt. For ARM -GICv2 mode, foreign interrupt is sent as IRQ which is always handled in normal -world. Foreign interrupt exit is similar to RPC exit but it is -`thread_irq_handler()` and `elx_irq()` (respectively for ARMv7-A/Aarch32 and -for Aarch64) that saves the thread state instead. The thread is resumed in the -same way though. -For ARM GICv3 mode, foreign interrupt is sent as FIQ which could be handled by -either secure world (EL3 in AArch64) or normal world. This mode is not supported -yet. - -*Notes for ARMv7/AArch32:* -SP_IRQ is initialized to temp stack instead of a separate stack. Prior to -exiting to normal world CPU state is changed to SVC and temp stack is selected. - -*Notes for AArch64:* -`SP_EL0` is assigned temp stack and is selected during IRQ processing. The -original `SP_EL0` is saved in the thread context to be restored when resuming. - -## Resume entry -OP-TEE is entered using the temp stack in the same way as for normal entry. The -thread to resume is looked up and the state is restored to resume execution. The -procedure to resume from an RPC exit or an foreign interrupt exit is exactly -the same. - -## Syscall -Syscalls are executed using the thread stack. - -*Notes for ARMv7/AArch32*: -Nothing special `SP_SVC` is already set with thread stack. - -*Notes for syscall AArch64*: - -Early in the exception processing the original `SP_EL0` is saved in `struct -thread_svc_regs` in case the TA is executed in AArch64. - -Current thread stack is assigned to `SP_EL0` which is then selected. - -When returning `SP_EL0` is assigned what is in `struct thread_svc_regs`. This -allows `tee_svc_sys_return_helper()` having the syscall exception handler return -directly to `thread_unwind_user_mode()`. - -# 7. Shared Memory -Shared Memory is a block of memory that is shared between the non-secure and the -secure world. It is used to transfer data between both worlds. - -## Shared Memory Allocation -The shared memory is allocated by the Linux driver from a pool `struct -shm_pool`, the pool contains: -* The physical address of the start of the pool -* The size of the pool -* Whether or not the memory is cached -* List of chunk of memory allocated. - -Note that: -- The shared memory pool is physically contiguous. -- The shared memory area is not secure as it is used by both non-secure and - secure world. - -### Shared Memory Configuration -It is the Linux kernel driver for OP-TEE that is responsible for initializing -the shared memory pool, given information provided by the OP-TEE core. The Linux -driver issues a SMC call `OPTEE_SMC_GET_SHM_CONFIG` to retrieve the information -* Physical address of the start of the pool -* Size of the pool -* Whether or not the memory is cached - -The shared memory pool configuration is platform specific. The memory mapping, -including the area `MEM_AREA_NSEC_SHM` (shared memory with non-secure world), is -retrieved by calling the platform-specific function `bootcfg_get_memory()`. -Please refer to this function and the area type `MEM_AREA_NSEC_SHM` to see the -configuration for the platform of interest. The Linux driver will then -initialize the shared memory pool accordingly. - -### Shared Memory Chunk Allocation -It is the Linux kernel driver for OP-TEE that is responsible for allocating -chunks of shared memory. OP-TEE linux kernel driver relies on linux kernel -generic allocation support (`CONFIG_GENERIC_ALLOCATION`) to allocation/release -of shared memory physical chunks. OP-TEE linux kernel driver relies on linux -kernel dma-buf support (`CONFIG_DMA_SHARED_BUFFER`) to track shared memory -buffers references. - -## Shared Memory Usage - -### From the Client Application -The client application can ask for shared memory allocation using the -GlobalPlatform Client API function `TEEC_AllocateSharedMemory()`. The client -application can also provide shared memory through the GlobalPlatform Client API -function `TEEC_RegisterSharedMemory()`. In such a case, the provided memory must -be physically contiguous so that the OP-TEE core, that does not handle -scatter-gather memory, is able to use the provided range of memory addresses. -Note that the reference count of a shared memory chunk is incremented when -shared memory is registered, and initialized to 1 on allocation. - -### From the Linux Driver -Occasionally the Linux kernel driver needs to allocate shared memory for the -communication with secure world, for example when using buffers of type -TEEC_TempMemoryReference. - -### From the OP-TEE core -In case the OP-TEE core needs information from the TEE supplicant (dynamic TA -loading, REE time request,...), shared memory must be allocated. Allocation -depends on the use case. The OP-TEE core asks for the following shared memory -allocation: -- `optee_msg_arg` structure, used to pass the arguments to the non-secure world, - where the allocation will be done by sending a `OPTEE_SMC_RPC_FUNC_ALLOC` - message. -- In some cases, a payload might be needed for storing the result from TEE - supplicant, for example when loading a Trusted Application. This type of - allocation will be done by sending the message - `OPTEE_MSG_RPC_CMD_SHM_ALLOC(OPTEE_MSG_RPC_SHM_TYPE_APPL,...)`, which then - will return: - - the physical address of the shared memory - - a handle to the memory, that later on will be used later on when freeing - this memory. - -### From the TEE Supplicant -The TEE supplicant is also working with shared memory, used to exchange data -between normal and secure worlds. The TEE supplicant receives a memory address -from the OP-TEE core, used to store the data. This is for example the case when a -Trusted Application is loaded. In this case, the TEE supplicant must register -the provided shared memory in the same way a client application would do, -involving the Linux driver. - -# 8. Pager -OP-TEE currently requires ~256 KiB RAM for OP-TEE kernel memory. This is not a -problem if OP-TEE uses TrustZone protected DDR, but for security reasons OP-TEE -may need to use TrustZone protected SRAM instead. The amount of available SRAM -varies between platforms, from just a few KiB up to over 512 KiB. Platforms with -just a few KiB of SRAM cannot be expected to be able to run a complete TEE -solution in SRAM. But those with 128 to 256 KiB of SRAM can be expected to have -a capable TEE solution in SRAM. The pager provides a solution to this by demand -paging parts of OP-TEE using virtual memory. - -## Secure memory -TrustZone protected SRAM is generally considered more secure than TrustZone -protected DRAM as there is usually more attack vectors on DRAM. The attack -vectors are hardware dependent and can be different for different platforms. - -## Backing store -TrustZone protected DRAM or in some cases non-secure DRAM is used as backing -store. The data in the backing store is integrity protected with one hash -(SHA-256) per page (4KiB). Readonly pages are not encrypted since the OP-TEE -binary itself is not encrypted. - -## Partitioning of memory -The code that handles demand paging must always be available as it would -otherwise lead to deadlock. The virtual memory is partitioned as: - -``` - Type Sections -+--------------+-----------------+ -| | text | -| | rodata | -| | data | -| unpaged | bss | -| | heap1 | -| | nozi | -| | heap2 | -+--------------+-----------------+ -| init / paged | text_init | -| | rodata_init | -+------------- +-----------------+ -| paged | text_pageable | -| | rodata_pageable | -+--------------+-----------------+ -| demand alloc | | -| | | -+--------------+-----------------+ -``` -Where "`nozi`" stands for "not zero initialized", this section contains entry -stacks (thread stack when TEE pager is not enabled) and translation tables (TEE -pager cached translation table when the pager is enabled and LPAE MMU is used). - -The "`init`" area is available when OP-TEE is initializing and contains -everything that is needed to initialize the pager. After the pager has been -initialized this area will be used for demand paged instead. - -The "`demand alloc`" area is a special area where the pages are allocated and -removed from the pager on demand. Those pages are returned when OP-TEE does not -need them any longer. The thread stacks currently belongs this area. This means -that when a stack is not used the physical pages can be used by the pager for -better performance. - -The technique to gather code in the different area is based on compiling all -functions and data into separate sections. The unpaged text and rodata is then -gathered by linking all object files with `--gc-sections` to eliminate sections -that are outside the dependency graph of the entry functions for unpaged -functions. A script analyzes this ELF file and generates the bits of the final -link script. The process is repeated for init text and rodata. What is not -"unpaged" or "init" becomes "paged". - -## Partitioning of the binary - -*Note: the struct definitions provided in this section are explicitly covered -by the following dual license:* -``` -SPDX-License-Identifier: (BSD-2-Clause OR GPL-2.0) -``` - -The binary is partitioned into four parts as: -``` -+----------+ -| Header | -+----------+ -| Init | -+----------+ -| Hashes | -+----------+ -| Pageable | -+----------+ -``` -Header is defined as: -```c -#define OPTEE_MAGIC 0x4554504f -#define OPTEE_VERSION 1 -#define OPTEE_ARCH_ARM32 0 -#define OPTEE_ARCH_ARM64 1 - -struct optee_header { - uint32_t magic; - uint8_t version; - uint8_t arch; - uint16_t flags; - uint32_t init_size; - uint32_t init_load_addr_hi; - uint32_t init_load_addr_lo; - uint32_t init_mem_usage; - uint32_t paged_size; -}; -``` - -The header is only used by the loader of OP-TEE, not OP-TEE itself. To -initialize OP-TEE the loader loads the complete binary into memory and copies -what follows the header and the following `init_size` bytes to -`(init_load_addr_hi << 32 | init_load_addr_lo)`. `init_mem_usage` is used by the -loader to be able to check that there is enough physical memory available for -OP-TEE to be able to initialize at all. The loader supplies in `r0/x0` the -address of the first byte following what was not copied and jumps to the load -address to start OP-TEE. - -In addition to overall binary with partitions inside described as above, extra -three binaries are generated simultaneously during build process for loaders -who support loading separate binaries: -``` -+----------+ -| Header | -+----------+ - -+----------+ -| Init | -+----------+ -| Hashes | -+----------+ - -+----------+ -| Pageable | -+----------+ -``` -In this case, loaders load header binary first to get image list and information -of each image; and then load each of them into specific load address assigned -in structure. These binaries are named with v2 suffix to distinguish from the -existing binaries. Header format is updated to help loaders loading binaries -efficiently: -```c -#define OPTEE_IMAGE_ID_PAGER 0 -#define OPTEE_IMAGE_ID_PAGED 1 - -struct optee_image { - uint32_t load_addr_hi; - uint32_t load_addr_lo; - uint32_t image_id; - uint32_t size; -}; - -struct optee_header_v2 { - uint32_t magic; - uint8_t version; - uint8_t arch; - uint16_t flags; - uint32_t nb_images; - struct optee_image optee_image[]; -}; -``` - -Magic number and architecture are identical as original. Version is increased -to 2. `load_addr_hi` and `load_addr_lo` may be 0xFFFFFFFF for pageable binary -since pageable part may get loaded by loader into dynamic available position. -`image_id` indicates how loader handles current binary. -Loaders who don't support separate loading just ignore all v2 binaries. - -## Initializing the pager -The pager is initialized as early as possible during boot in order to minimize -the "init" area. The global variable `tee_mm_vcore` describes the virtual memory -range that is covered by the level 2 translation table supplied to -`tee_pager_init()`. - -### Assign pageable areas -A virtual memory range to be handled by the pager is registered with a call to -`tee_pager_add_core_area()`. - -```c -bool tee_pager_add_area(tee_mm_entry_t *mm, uint32_t flags, const void *store, - const void *hashes); -``` - -which takes a pointer to `tee_mm_entry_t` to tell the range, flags to tell how -memory should be mapped (readonly, execute etc), and pointers to backing store -and hashes of the pages. - -### Assign physical pages -Physical SRAM pages are supplied by calling `tee_pager_add_pages()` - -```c -void tee_pager_add_pages(tee_vaddr_t vaddr, size_t npages, bool unmap); -``` - -`tee_pager_add_pages()` takes the physical address stored in the entry mapping -the virtual address "vaddr" and "npages" entries after that and uses it to map -new pages when needed. The unmap parameter tells whether the pages should be -unmapped immediately since they does not contain initialized data or be kept -mapped until they need to be recycled. The pages in the "init" area are supplied -with `unmap == false` since those page have valid content and are in use. - -## Invocation -The pager is invoked as part of the abort handler. A pool of physical pages are -used to map different virtual addresses. When a new virtual address needs to be -mapped a free physical page is mapped at the new address, if a free physical -page cannot be found the oldest physical page is selected instead. When the page -is mapped new data is copied from backing store and the hash of the page is -verified. If it is OK the pager returns from the exception to resume the -execution. - -## Paging of user TA - -Paging of user TAs can optionally be enabled with CFG_PAGED_USER_TA=y. -Paging of user TAs is analogous to paging of OP-TEE kernel parts but with a -few differences: -- Read/write pages are paged in addition to read-only pages -- Page tables are managed dynamically - -tee_pager_add_uta_area() is used to setup initial read/write mapping needed -when populating the TA. When the TA is fully populated and relocated -tee_pager_set_uta_area_attr() changes the mapping of the area to strict -permissions used when the TA is running. - -# 9. Memory objects - -A memory object, MOBJ, describes a piece of memory. The interface provided -is mostly abstract when it comes to using the MOBJ to populate translation -tables etc. - -There is different kinds of MOBJs describing: -- physically contiguous memory - - created with mobj_phys_alloc() -- virtual memory - - one instance with the name mobj_virt available - - spans the entire virtual address space -- physically contiguous memory allocated from a tee_mm_pool_t * - - created with mobj_mm_alloc() -- paged memory - - created with mobj_paged_alloc() - - only contains the supplied size and makes mobj_is_paged() return true if - supplied as argument -- secure copy paged shared memory - - created with mobj_seccpy_shm_alloc() - - makes mobj_is_paged() and mobj_is_secure() return true if supplied as - argument - -# 10. Cryptographic abstraction layer -Cryptographic operations are implemented inside the TEE core by the -[LibTomCrypt] library. An abstraction layer allows for replacing the default -implementation, as explained in [crypto.md]. - -# 11. libutee - -The GlobalPlatform Core Internal API describes services that are provided to -Trusted Applications. libutee is a library that implements this API. - -libutee is a static library the Trusted Applications shall statically link -against. Trusted Applications do execute in non-privileged secure userspace and -libutee also aims at being executed in the non-privileged secure userspace. - -Some services for this API are fully statically implemented inside the -libutee library while some services for the API are implemented inside the -OP-TEE core (privileged level) and libutee calls such services through -system calls. - -# 12. Trusted Applications - -## Pseudo TAs and User Mode TAs - -There are two ways to implement Trusted Applications (TAs), pseudo TAs and -user mode TAs. User mode TAs are full featured Trusted Applications as -specified by the GlobalPlatform TEE specifications, these are simply referred -to as 'Trusted Applications'. For most cases, user mode TAs are preferred. - -### Pseudo Trusted Applications - -These are implemented directly to the OP-TEE core tree in, eg, -`core/arch/arm/pta`, and are built along with and statically built into the -OP-TEE core blob. - -The pseudo Trusted Applications included in OP-TEE already are OP-TEE -secure privileged level services hidden behind a "GlobalPlatform TA Client" API. -These pseudo-TAs are used for various purposes such as specific secure services -or embedded tests services. - -Pseudo TAs do not benefit from the GlobalPlatform Core Internal API support -specified by the GlobalPlatform TEE specs. These APIs are provided to TAs as a -static library each TA shall link against (the "libutee") and that calls OP-TEE -core service through system calls. As OP-TEE core does not link with libutee, -Pseudo TAs can only use the OP-TEE core internal APIs and routines. - -As pseudo TAs have the same privileged execution level as the OP-TEE core code -itself, such situation may not be desirable for complex TAs. - -In most cases an unprivileged (user mode) TA is the best choice instead of adding -your code directly to the OP-TEE core. However if you decide your application -is best handled directly in OP-TEE core like this, you can look at -`core/arch/arm/pta/stats.c` as a template and just add your pseudo TA based on -that to the `sub.mk` in the same directory. - -### User Mode Trusted Applications - -User Mode Trusted Applications are loaded (mapped into memory) by OP-TEE -core in the Secure World when something in the REE wants to talk to that -particular application UUID. They run at a lower CPU privilege level -than OP-TEE core code. In that respect, they are quite similar to regular -applications running in the Rich Execution Environment (REE), except that -they execute in Secure World. - -Trusted Application benefit from the GlobalPlatform Core Internal API as -specified by the GlobalPlatform TEE specifications. - -There are several types of user mode TAs, which differ by the way they are -stored. - -#### "Normal" or Secure Storage Trusted Applications - -These are stored in secure storage. The meta data is stored in a database -of all installed TAs and the actual binary is stored encrypted as a -separate file in the untrusted REE filesystem. - -Before these TAs can be loaded they have to be installed first, this is -something that can be done during initial deployment or at a later stage. - -For test purposes the test program xtest can install a TA into secure -storage with the command: -``` -xtest --install-ta -``` - -#### "Legacy" or REE FS Trusted Applications - -They consist of a cleartext signed ELF file, named from the UUID -of the TA and the suffix ".ta". - -They are built separately from the OP-TEE core boot-time blob, although when -they are built they use the same build system, and are signed with the key -from the build of the original OP-TEE core blob. - -Because the TAs are signed, they are able to be stored in the untrusted REE -filesystem, and `tee-supplicant` will take care of passing them to be checked -and loaded by the Secure World OP-TEE core. - -#### Early Trusted Applications - -The so-called early TAs are virtually identical to the normal (REE FS) TAs, -but insted of being loaded from the Normal World file system, they are linked -into a special data section in the TEE core blob. Therefore, they are available -even before `tee-supplicant` and the Normal World filesystems have come up. -More details in commit [early_tas]. - -## Special treatment of Trusted Applications - -### Syscalls - -User mode TAs are not directly bound to function exports in the OP-TEE -core blob, both because the TA code is kept at arm's length by executing at a -different privileged level, and because TAs direct binding to addresses in the -core would require upgrades of all TAs synchronusly with upgrades of the -OP-TEE core blob. Instead, the resolution of OP-TEE core exports in the TA -is done at runtime. - -OP-TEE does this by using syscalls, the same kind of way as the Linux kernel -provides a stable API for its userland programs. TAs are written to use -syscall wrappers to access functions exported from OP-TEE core, so this all -happens automatically when a TA wants to use an API exported from OP-TEE -core. - -Pseudo TAs and anything else directly built into OP-TEE core do not -require going through a syscall interface, since they can just link directly -as they are directly part of the core. - -Most of the services defined by the GlobalPlatform Core Internal API are -implemented through syscall from the TA to the OP-TEE core privileged level: -cryptographic services, communications with other TAs, ... Some services were -added through OP-TEE development such as ASCII message tracing. - -Syscalls are provided already for all public exports from OP-TEE core that a -Dynamic TA is expected to use, so you only need to take care about this if -you will add new exported from OP-TEE core that TAs will want to use. - -### Malloc mapping - -The OP-TEE core code has its own private memory allocation heap that is mapped -into its MMU view only and cannot be seen by Trusted Applications. The -core code uses `malloc()` and `free()` style APIs. - -Trusted Applications also have their own private memory allocation heaps -that are visible to the owning TA, and to OP-TEE core. TAs manage their -heaps using `TEE_Malloc()` and `TEE_Free()` style apis. - -Heap |Visible to |Inaccessible to ------|-------------|--------------- -core |core |any TA -TA |core, same TA|any other TA - -This enforces "Chinese Walls" between the TA views of Secure World. - -Since OP-TEE core cannot perform allocations in the TA's private heap, -and the TA is not going to be able to access allocations from the OP-TEE -core heap, it means only allocations from the TA heap are visible to both the -TA and OP-TEE core. When performing syscalls between a TA and OP-TEE core -then, the TA side must provide all the memory allocations for buffers, etc -used by both sides. - -### Malloc pool - -The OP-TEE core malloc heap is defined by `CFG_CORE_HEAP_SIZE` in `mk/config.mk`. - -However for TAs, the individual TA TEE_Malloc() heap size is defined by -`TA_DATA_SIZE` in `user_ta_header_defines.h`. Likewise the TA stack size is -set in the same file, in `TA_STACK_SIZE`. - -## File format of a Dynamic Trusted Application - -The format a TA is: -``` -<Signed header> -<ELF> -``` - -Where `<ELF>` is the content of a standard ELF file and `<Signed header>` -consists of: - -| Type | Name | Comment | -|------|------|---------| -| `uint32_t` | magic | Holds the magic number `0x4f545348` | -| `uint32_t` | img_type | image type, values defined by enum shdr_img_type | -| `uint32_t` | img_size | image size in bytes | -| `uint32_t` | algo | algorithm, defined by public key algorithms `TEE_ALG_*` from TEE Internal API specification | -| `uint16_t` | hash_size | size of the signed hash | -| `uint16_t` | sig_size | size of the signature | -| `uint8_t[hash_size]` | hash | Hash of the fields above and the `<ELF>` above | -| `uint8_t[sig_size]` | signature | Signature of hash | - -# 13. Device Tree support - -OP-TEE core can use the device tree format to inject platform configuration -information during platform initialization and possibly some run time contexts. - -Device Tree technology allows to describe platforms from ASCII source files -so-called DTS files. These can be used to generate a platform description -binary image, so-called DTB, embedded in the platform boot media for -applying expected configuration settings during the platform initializations. - -This scheme relaxes design constraints on the OP-TEE core implementation as -most of the platform specific hardware can be tuned without modifying C -source files or adding configuration directives in the build environments. - -## Secure and Non-Secure Device Trees - -There can be several device trees embedded in the target system and some -can be shared across the boot stages. - -* Boot loader stages may load a device tree structure in memory for all boot -stage to get platform configuration from. If such device tree data are to be -accessed by the non-secure world, they shall be located in non-secure memory. - -* Boot loader stages may load a device tree structure in secure memory for -the benefit of the secure world only. Such device tree blob shall be located -in secure memory. - -* OP-TEE core can also embedded a device tree structure to describe the -platform. - -* Non-secure world can embed a device tree structure and/or rely on a device -tree structure loaded by the secure world, being an early boot stage and/or -OP-TEE core. - -Obviously the non-secure world will not be able to access a device tree -image located on a secure memory which non-secure world as no access to. - -## Early boot device tree argument - -The bootloader provides arguments to the OP-TEE core when it -boots it. Among those, the physical memory base address of a device tree -image accessible to OP-TEE core. - -When OP-TEE core is built with `CFG_DT=y` this device tree is accessed by -OP-TEE core to get some information: console configuration, main memory -size. - -OP-TEE will also try to add the description of the OP-TEE resources for -the non-secure world to properly communicate with OP-TEE. This assumes the -image is located in non-secure memory. - -Modifications made by OP-TEE core on the non-secure device tree image provided -by early boot and passed to non-secure world are the following: -- Add an OP-TEE node if none found with the related invocation parameters. -- Add a reserved memory node for the few memory areas that shall be reserved - to the secure world and non accessed by the non-secure world. -- Add a PSCI description node if none found. - -Early boot DTB located in non-secure memory can be accessed by OP-TEE core -only during its initialization, before non-secure world boots. - -## Early boot device tree overlay - -There are two possibilities for OP-TEE core to provide a device tree -overlay to the non-secure world. - -* Append OP-TEE nodes to an existing DTB overlay located at CFG_DT_ADDR or - passed in arg2 - -* Generate a new DTB overlay at CFG_DT_ADDR if and only if CFG_DT_ADDR does - not point to a valid DTB. - -A subsequent boot stage should merge the OP-TEE DTB overlay into another -DTB. - -A typical bootflow for this would be - -ATF -> OP-TEE -> u-boot with u-boot merging the OP-TEE DTB overlay located -at CFG_DT_ADDR into a DTB u-boot has loaded from elsewhere. - -This functionality is enabled when `CFG_EXTERNAL_DTB_OVERLAY=y`. - -## Embedded Secure Device Tree - -When OP-TEE core is built with configuration directive `CFG_EMBED_DTB=y` -directive `CFG_EMBED_DTB_SOURCE_FILE` shall provide the relative path of the -DTS file inside directory `core/arch/$(ARCH)/dts` from which a DTB is -generated and embedded in a read-only section of OP-TEE core. - -In this case the device tree address passed to the OP-TEE entry point -by the bootloader is ignored, only the embedded device tree is accessible. - -[crypto.md]: crypto.md -[early_tas]: https://github.com/OP-TEE/optee_os/commit/d0c636148b3a -[LibTomCrypt]: https://github.com/libtom/libtomcrypt -[OP-TEE Client]: https://github.com/OP-TEE/optee_client -[OP-TEE Linux Kernel driver]: https://github.com/linaro-swg/linux -[OP-TEE Trusted OS]: https://github.com/OP-TEE/optee_os -[optee_smc.h]: ../core/arch/arm/include/sm/optee_smc.h -[optee_msg.h]: ../core/include/optee_msg.h -[Platforms Supported]: https://github.com/OP-TEE/optee_os#3-platforms-supported -[struct optee_msg_arg]: ../core/include/optee_msg.h -[thread.c]: ../core/arch/arm/kernel/thread.c diff --git a/documentation/optee_with_auth_framework.md b/documentation/optee_with_auth_framework.md deleted file mode 100644 index c654e526..00000000 --- a/documentation/optee_with_auth_framework.md +++ /dev/null @@ -1,20 +0,0 @@ -## OP-TEE with authentication framework in ARM-TF -This document gives a brief description on how to enable the verification of OP-TEE using the authentication framework in ARM-TF - ---- -## What we should do -* According to [user-guide.md](https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.md), there is no additional specific build options for the verification of OP-TEE. If we have enabled the authentication framework and specified the BL32 build option when building ARM-TF, the BL32 related certificates will be created automatically by the cert_create tool, and then these certificates will be verified during booting up. - - -* To enable the authentication framework, the following steps should be followed according to [user-guide.md](https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.md). All the details for these build options are also in [user-guide.md](https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/user-guide.md), more details about the authentication framework, please see [auth-framework.md](https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/auth-framework.md) and [trusted-board-boot.md](https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/trusted-board-boot.md). - - * Check out a recent version of the [mbed TLS Repository](https://github.com/ARMmbed/mbedtls.git), and then switch to tag mbedtls-2.2.0 - * Besides the normal build options, add the following build options for ARM-TF - * **MBEDTLS_DIR**=*path of the directory containing mbed TLS sources* - * **TRUSTED_BOARD_BOOT**=*1* - * **GENERATE_COT**=*1* - * **ARM_ROTPK_LOCATION**=*devel_rsa* - * **ROT_KEY**=*$(ARM_TF_PATH)/plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem* - - -* Above steps have been tested on FVP platform, all verification steps are ok and xtest can run successfully without regression. diff --git a/documentation/porting_guidelines.md b/documentation/porting_guidelines.md deleted file mode 100644 index a7b966cd..00000000 --- a/documentation/porting_guidelines.md +++ /dev/null @@ -1,378 +0,0 @@ -Porting guidelines for OP-TEE -============================= - -1. [Introduction](#1-introduction) -2. [Add a new platform](#2-add-a-new-platform) -3. [Hardware Unique Key](#3-hardware-unique-key) -4. [Secure Clock](#4-secure-clock) -5. [Root and Chain of Trust](#5-root-and-chain-of-trust) -6. [Hardware Crypto IP](#6-hardware-crypto-ip) -7. [Power Management / PSCI](#7-power-management--psci) -8. [Memory firewalls / TZASC](#8-memory-firewalls--tzasc) -9. [Trusted Application private/public keypair](#9-trusted-application-privatepublic-keypair) - -## 1. Introduction ---------------- -This document serves a dual purpose: -* Serve as a base for getting OP-TEE up and running on a new device with initial - xtest validation passing. This is the first part of this document (section 2). -* Highlight the missing pieces if you intend to make a real secure product, - that is what the second part of this document is about. - -We are trying our best to implement full end to end security in OP-TEE in a -generic way, but due to the nature of devices being different, NDA etc, it is -not always possible for us to do so and in those cases, we most often try to -write a generic API, but we will just stub the code. This porting guideline -highlights the missing pieces that must be addressed in a real secure consumer -device. Hopefully we will sooner or later get access to devices where we at -least can make reference implementations publicly available to everyone for the -missing pieces we are talking about here. - -## 2. Add a new platform -The first thing you need to do after you have decided to port OP-TEE to another -device is to add a new platform device. That can either be adding a new platform -variant (`PLATFORM_FLAVOR`) if it is a device from a family already supported, -or it can be a brand new platform family (`PLATFORM`). Typically this initial -setup involve configuring UART, memory addresses etc. For simplicity let us call -our fictive platform for "gendev" just so we have something to refer to when -writing examples further down. - -### 2.1 core/arch/arm -In `core/arch/arm` you will find all the currently supported devices. That is -where you are supposed to add a new platform or modify an existing one. -Typically you will find this set of files in a specific platform folder: -```bash -$ ls -conf.mk main.c platform_config.h sub.mk -``` - -So for the gendev platform it means that the files should be placed in this -folder: -```bash -core/arch/arm/plat-gendev -``` - -##### conf.mk -This is the device specific makefile where you define configurations unique to -your platform. This mainly comprises two things: -- OP-TEE configuration variables (`CFG_`), which may be assigned values in two -ways. `CFG_FOO ?= bar` should be used to provide a default value that may be -modified at compile time. On the other hand, variables that must be set to some -value and cannot be modified should be set by: `$(call force,CFG_FOO,bar)`. -- Compiler flags for the TEE core, the user mode libraries and the Trusted -Applications, which may be added to macros used by the build system. Please see -[Platform-specific configuration and flags] in the build system documentation. - -It is recommended to use a existing platform configuration file as a starting -point. For instance, [core/arch/arm/plat-hikey/conf.mk]. - -The platform `conf.mk` file should at least define the default platform flavor -for the platform, the core configurations (architecture and number of cores), -the main configuration directives (generic boot, arm trusted firmware support, -generic time source, console driver, etc...) and some platform default -configuration settings. - -```makefile -PLATFORM_FLAVOR ?= hikey - -include core/arch/arm/cpu/cortex-armv8-0.mk - -$(call force,CFG_TEE_CORE_NB_CORE,8) -$(call force,CFG_GENERIC_BOOT,y) -$(call force,CFG_PL011,y) -$(call force,CFG_PM_STUBS,y) -$(call force,CFG_SECURE_TIME_SOURCE_CNTPCT,y) -$(call force,CFG_WITH_ARM_TRUSTED_FW,y) -$(call force,CFG_WITH_LPAE,y) - -CFG_NUM_THREADS ?= 8 -CFG_CRYPTO_WITH_CE ?= y -CFG_WITH_STACK_CANARIES ?= y -CFG_CONSOLE_UART ?= 3 -CFG_DRAM_SIZE_GB ?= 2 -``` - -##### main.c -This platform specific file will contain power management handlers and code -related to the UART. We will talk more about the information related to the -handlers further down in this document. For our gendev device it could look like -this (here we are excluding the necessary license header to save some space): - -```c -#include <console.h> -#include <drivers/serial8250_uart.h> -#include <kernel/generic_boot.h> -#include <kernel/panic.h> -#include <kernel/pm_stubs.h> -#include <mm/core_mmu.h> -#include <platform_config.h> -#include <stdint.h> -#include <tee/entry_fast.h> -#include <tee/entry_std.h> - -static void main_fiq(void) -{ - panic(); -} - -static const struct thread_handlers handlers = { - .std_smc = tee_entry_std, - .fast_smc = tee_entry_fast, - .nintr = main_fiq, - .cpu_on = cpu_on_handler, - .cpu_off = pm_do_nothing, - .cpu_suspend = pm_do_nothing, - .cpu_resume = pm_do_nothing, - .system_off = pm_do_nothing, - .system_reset = pm_do_nothing, -}; - -const struct thread_handlers *generic_boot_get_handlers(void) -{ - return &handlers; -} - -/* - * Register the physical memory area for peripherals etc. Here we are - * registering the UART console. - */ -register_phys_mem(MEM_AREA_IO_NSEC, CONSOLE_UART_BASE, SERIAL8250_UART_REG_SIZE); - -static struct serial8250_uart_data console_data; - -void console_init(void) -{ - serial8250_uart_init(&console_data, CONSOLE_UART_BASE, - CONSOLE_UART_CLK_IN_HZ, CONSOLE_BAUDRATE); - register_serial_console(&console_data.chip); -} -``` - -##### platform_config.h -This is a mandatory header file for every platform, since there are several -files relaying upon the existence of this particular file. This file is where -you will find the major differences between different platforms, since this is -where you do the memory configuration, define base addresses etc. we are going to -list a few here, but it probably makes more sense to have a look at the already -existing `platform_config.h` files for the other platforms. Our fictive gendev -could look like this: - -```c -#ifndef PLATFORM_CONFIG_H -#define PLATFORM_CONFIG_H - -/* Make stacks aligned to data cache line length */ -#define STACK_ALIGNMENT 64 - -/* 8250 UART */ -#define CONSOLE_UART_BASE 0xcafebabe /* UART0 */ -#define CONSOLE_BAUDRATE 115200 -#define CONSOLE_UART_CLK_IN_HZ 19200000 - -/* Optional: when used with CFG_WITH_PAGER, defines the device SRAM */ -#define TZSRAM_BASE 0x3F000000 -#define TZSRAM_SIZE (200 * 1024) - -/* Mandatory main secure RAM usually DDR */ -#define TZDRAM_BASE 0x60000000 -#define TZDRAM_SIZE (32 * 1024 * 1024) - -/* Mandatory TEE RAM location and core load address */ -#define TEE_RAM_START TZDRAM_BASE -#define TEE_RAM_PH_SIZE TEE_RAM_VA_SIZE -#define TEE_RAM_VA_SIZE (4 * 1024 * 1024) -#define TEE_LOAD_ADDR (TZDRAM_BASE + 0x20000) - -/* Mandatory TA RAM (external less secure RAM) */ -#define TA_RAM_START (TZDRAM_BASE + TEE_RAM_VA_SIZE) -#define TA_RAM_SIZE (TZDRAM_SIZE - TEE_RAM_VA_SIZE) - -/* Mandatory: for static SHM, need a hardcoded physical address */ -#define TEE_SHMEM_START 0x08000000 -#define TEE_SHMEM_SIZE (4 * 1024 * 1024) - -#endif /* PLATFORM_CONFIG_H */ -``` -This is minimal amount of information in the `platform_config.h` file. I.e, the -memory layout for on-chip and external RAM. Note that parts of the DDR typically -will need to be shared with normal world, so there is need for some kind of -memory firewall for this (more about that further down). As you can see we have -also added the UART configuration here, i.e., the `DEVICE0_xyz` part. - -### 2.2 Devices officially in OP-TEE? -We do encourage everyone to submit their board support to the OP-TEE project -itself, so it becomes part of the official releases and will be maintained by -the OP-TEE community itself. If you intend to do so, then there are a few more -things that you are supposed to do. - -#### 2.2.1 Update README.md -There is a section ([3. Platforms Supported]) that lists all devices officially -supported in OP-TEE, that is where you also shall list your device. It should -contain the name of the platform, then composite `PLATFORM` flag and whether the -device is publicly available or not. - -#### 2.2.2 Update .shippable.yml -Since we are using Shippable to test pull requests etc, we would like that you also -add your device to the [.shippable.yml](../.shippable.yml) file, so that it will at least be built when -someone is doing a pull request. Add a line at the end of file: - -``` - - _make PLATFORM=<platform-name>_ -``` -#### 2.2.3 Maintainer -If you are submitting the board support upstream and cannot give Linaro -maintainers a device, then we are going to ask you to become the maintainer for -the device you have added. This means that you should also update the -[MAINTAINERS.md] file accordingly. By being a maintainer for a device you are -responsible to keep it up to date and you will be asked every quarter as part of -the OP-TEE release schedule to test your device running the latest OP-TEE -software. - -#### 2.2.4 Update build.git -This isn't strictly necessary, but we are trying to create repo setup(s) for the -device(s) that we are in charge of. That makes it very easy for newcomers to get -started with a certain platform. So please consider creating a new [manifest] -for the device you have added to OP-TEE. - -## 3. Hardware Unique Key -Most devices have some kind of Hardware Unique Key (HUK) that is mainly used to -derive other keys. The HUK could for example be used when deriving keys used in -secure storage etc. The important thing with the HUK is that it needs to be well -protected and in the best case the HUK should never ever be readable directly -from software, not even from the secure side. There are different solutions to -this, crypto accelerator might have support for it or, it could involve another -secure co-processor. - -In OP-TEE the HUK **is** just **stubbed** and you will see that in the function -called `tee_otp_get_hw_unique_key()` in `core/include/kernel/tee_common_otp.h`. -In a real secure product you **must** replace this with something else. If your -device lacks the hardware support for a HUK, then you must at least change this -to something else than just zeroes. But, remember it is not good secure practice -to store a key in software, especially not the key that is the root for -everything else, so this is not something we recommend that you should do. - -## 4. Secure Clock -The Time API in GlobalPlatform Internal Core API specification defines three -sources of time; system time, TA persistent time and REE time. The REE time -is by nature considered as an unsecure source of time, but the other two should -in a fully trustable hardware make use of trustable source of time, i.e., a -secure clock. Note that from GlobalPlatform point of view it is not required to -make use of a secure clock, i.e., it is OK to use time from REE, but the level -of trust should be reflected by the `gpd.tee.systemTime.protectionLevel` -property and the `gpd.tee.TAPersistentTime.protectionLevel` property (100=REE -controlled clock, 1000=TEE controlled clock). So the functions that one needs to -pay attention to are `tee_time_get_sys_time()` and `tee_time_get_ta_time()`. If -your hardware has a secure clock, then you probably want to change the -implementation there to instead use the secure clock (and then you would also -need to update the property accordingly, i.e., -`tee_time_get_sys_time_protection_level()` and the variable `ta_time_prot_lvl` -in `tee_svc.c`). - -## 5. Root and Chain of Trust -To be able to assure that your devices are running the (untampered) binaries you -intended to run you will need to establish some kind of trust anchor on the -devices. - -The most common way of doing that is to put the root public key in some -read only memory on the device. Quite often SoC's/OEM's stores public key(s) -directly or the hash(es) of the public key(s) in [OTP]. When the boot ROM (which -indeed needs to be ROM) is about to load the first stage bootloader it typically -reads the public key from the software binary itself, hash the key and compare -it to the key in OTP. If they are matching, then the boot ROM can be sure that -the first stage bootloader was indeed signed with the corresponding private key. - -In OP-TEE you will not find any code at all related to this and this is a good -example when it is hard for us to do this in a generic way since device -manufacturers all tend to do this in their own unique way and they are not very -keen on sharing their low level boot details and security implementation with -the rest of the world. This is especially true on ARMv7-A. For ARMv8-A it looks -bit better, since ARM in ARM Trusted Firmware have implemented and defined how a -abstract the chain of trust (see [auth-framework.rst]). We have successfully -verified OP-TEE by using the authentication framework from ARM Trusted Firmware -(see [optee_with_auth_framework.md] for the details). - -## 6. Hardware Crypto IP -By default OP-TEE uses a software crypto library (currently LibTomCrypt) and you -have the ability to enable Crypto Extensions that were introduced with ARMv8-A -(if the device is capable of that). Some of the devices we have in our hands do -have hardware crypto IP's, but due to NDA's etc it has not been possible to -enable it. If you have a device capable of doing crypto operations on a -dedicated crypto block and you prefer to use that in favor for the software -implementation, then you will need to implement relevant functions defined in -`core/include/crypto/crypto.h`, the Crypto API, and write the low level -driver that communicates with the device. Our [crypto.md] file describes -how the Crypto API is integrated. Since the communication with crypto -blocks tends to be quite different depending on what kind of crypto block -you have, we have not written how that should be done. It might be that we -do that in the future when get hold of a device where we can use the crypto -block. - -By default OP-TEE is configured with a software PRNG. The entropy is added -to software PRNG at various places, but unfortunately it is still quite -easy to predict the data added as entropy. As a consequence, unless the RNG -is based on hardware the generated random will be quite weak. - -## 7. Power Management / PSCI -In section 2 when we talked about the file `main.c`, we added a couple of -handlers related to power management, we are talking about the following lines: -``` - .cpu_on = cpu_on_handler, - .cpu_off = pm_do_nothing, - .cpu_suspend = pm_do_nothing, - .cpu_resume = pm_do_nothing, - .system_off = pm_do_nothing, - .system_reset = pm_do_nothing, -``` -The only function that actually does something there is the `cpu_on` function, -the rest of them are stubbed. The main reason for that is because we think that -how to suspend and resume is a device dependent thing. The code in OP-TEE is -prepared so that callbacks etc from ARM Trusted Firmware will be routed to -OP-TEE, but since the function(s) are just stubbed we will not do anything and -just return. In a real production device, you would probably want to save and -restore CPU states, secure hardware IPs' registers and TZASC and other memory -firewall related setting when these callbacks are being called. - -## 8. Memory firewalls / TZASC -ARM have defined a system IP / SoC peripheral called TrustZone Address Space -Controller (TZASC, see [TZC-380] and [TZC-400]). TZASC can be used to configure -DDR memory into separate regions in the physcial address space, where each -region can have an individual security level setting. After enabling TZASC, it -will perform security checks on transactions to memory or peripherals. It is not -always the case that TZASC is on a device, in some cases the SoC has developed -something equivalent. In OP-TEE this is very well reflected, i.e., different -platforms have different ways of protecting their memory. On ARMv8-A platforms -we are in most of the cases using ARM Trusted Firmware as the boot firmware and -there the secure bootloader is the one that configures secure vs non-secure -memory using TZASC (see [plat_arm_security_setup] in ARM-TF). The takeaway here -is that you must make sure that you have configured whatever memory firewall your -device has such that it has a secure and a non-secure memory area. - -## 9. Trusted Application private/public keypair -By default all Trusted Applications (TA's) are signed with the pre-generated -2048-bit RSA development key (private key). This key is located in the `keys` -folder (in the root of optee_os.git) and is named `default_ta.pem`. This key -**must** be replaced with your own key and you should **never ever** check-in -this private key in the source code tree when in use in a real product. The -recommended way to store private keys is to use some kind of [HSM] (Hardware -Security Module), but an alternative would be temporary put the private key on a -computer considered as secure when you are about to sign TA's intended to be -used in real products. Typically it is only a few number of people having access -to this type of key in company. The key handling in OP-TEE is currently a bit -limited since we only support a single key which is used for all TA's. We have -plans on extending this to make it a bit more flexible. Exactly when that will -happen has not been decided yet. - -[3. Platforms Supported]: ../README.md#3-platforms-supported -[auth-framework.rst]: https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/auth-framework.rst -[crypto.md]: crypto.md -[HSM]: https://en.wikipedia.org/wiki/Hardware_security_module -[manifest]: https://github.com/OP-TEE/build#6-manifests -[MAINTAINERS.md]: ../MAINTAINERS.md -[optee_with_auth_framework.md]: optee_with_auth_framework.md -[OTP]: https://en.wikipedia.org/wiki/Programmable_read-only_memory -[plat_arm_security_setup]: https://github.com/ARM-software/arm-trusted-firmware/search?utf8=%E2%9C%93&q=plat_arm_security_setup&type= -[TZC-380]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0431c/index.html -[TZC-400]: http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.100325_0001_02_en/index.html -[travis]: ../.travis.yml -[Platform-specific configuration and flags]: build_system.md#platform-specific-configuration-and-flags -[core/arch/arm/plat-hikey/conf.mk]: ../core/arch/arm/plat-hikey/conf.mk diff --git a/documentation/secure_storage.md b/documentation/secure_storage.md deleted file mode 100644 index d2b6dd4f..00000000 --- a/documentation/secure_storage.md +++ /dev/null @@ -1,237 +0,0 @@ -# Secure Storage in OP-TEE - -## Background - -Secure Storage in OP-TEE is implemented according to what has been defined -in GloblaPlatform’s TEE Internal API specification (here called Trusted -Storage). This specification mandates that it should be possible to store -general-purpose data and key material that guarantees confidentiality and -integrity of the data stored and the atomicity of the operations that modifies -the storage (atomicity here means that either the entire operation completes -successfully or no write is done). - -There are currently two secure storage implementations in OP-TEE: - -- The first one relies on the normal world (REE) file system. It is described in - this document and is the default implementation. It is enabled at compile time - by `CFG_REE_FS=y`. -- The second one makes use of the Replay Protected Memory Block (RPMB) partition - of an eMMC device, and is enabled by setting `CFG_RPMB_FS=y`. It is described - in [secure_storage_rpmb.md](secure_storage_rpmb.md). - -It is possible to use the normal world file systems and the RPMB implementations -simultaneously. For this, two OP-TEE specific storage identifiers have been -defined: `TEE_STORAGE_PRIVATE_REE` and `TEE_STORAGE_PRIVATE_RPMB`. Depending -on the compile-time configuration, one or several values may be used. -The value `TEE_STORAGE_PRIVATE` selects the REE FS when available, otherwise the -RPMB FS (in this order). - -The rest of this document describes the REE FS only. - -## Overview - -![Secure Storage System Architecture](images/secure_storage/secure_storage_system_architecture.png -"Secure Storage System Architecture") - -### Source Files in OP-TEE OS - -| source file | | -| ----------- | --- | -| **[core/tee/tee_svc_storage.c](../core/tee/tee_svc_storage.c)** | TEE trusted storage service calls | -| **[core/tee/tee_ree_fs.c](../core/tee/tee_ree_fs)** | TEE file system & REE file operation interface | -| **[core/tee/fs_htree.c](../core/tee/fs_htree.c)** | Hash tree | -| **[core/tee/tee_fs_key_manager.c](../core/tee/tee_fs_key_manager.c)** | Key manager | -| **[lib/libutee/](../lib/libutee/)** | GlobalPlatform Internal API library | - -### Basic File Operation Flow - -When a TA is calling the write function provided by GP Trusted Storage API to -write data to a persistent object, a corresponding syscall implemented in TEE -Trusted Storage Service will be called, which in turn will invoke a series of -TEE file operations to store the data. TEE file system will then encrypt the -data and send REE file operation commands and the encrypted data to TEE -supplicant by a series of RPC messages. TEE supplicant will receive the -messages and store the encrypted data accordingly to the Linux file system. -Reading files are handled in a similar manner. - -### GlobalPlatform Trusted Storage Requirement - -Below is an excerpt from the specification, listing the most vital requirements: - -> 1. The Trusted Storage may be backed by non-secure resources as long as -> suitable cryptographic protection is applied, which MUST be as strong as -> the means used to protect the TEE code and data itself. -> 2. The Trusted Storage MUST be bound to a particular device, which means that -> it MUST be accessible or modifiable only by authorized TAs running in the -> same TEE and on the same device as when the data was created. -> 3. Ability to hide sensitive key material from the TA itself. -> 4. Each TA has access to its own storage space that is shared among all the -> instances of that TA but separated from the other TAs. -> 5. The Trusted Storage must provide a minimum level of protection against -> rollback attacks. It is accepted that the actually physical storage may be -> in an insecure area and so is vulnerable to actions from outside of the -> TEE. Typically, an implementation may rely on the REE for that purpose -> (protection level 100) or on hardware assets controlled by the TEE -> (protection level 1000). -> -> (see GP TEE Internal Core API section 2.5 and 5.2) - -If configured with `CFG_RPMB_FS=y` the protection against rollback is controlled -by the TEE and is set to 1000. If `CFG_RPMB_FS=n`, there's no protection against -rollback, and the protection level is set to 0. - -### TEE File Structure in Linux File System - -OP-TEE by default uses `/data/tee/` as the secure storage space in the Linux -file system. Each persistent object is assigned an internal identifier. It is -an integer which is visible in the Linux file system as -`/data/tee/<file number>`. - -A directory file, `/data/tee/dirf.db`, lists all the -objects that are in the secure storage. All normal world files are integrity -protected and encrypted, as described below. - -## Key Manager - -Key manager is an component in TEE file system, and is responsible for handling -data encryption and decryption and also management of the sensitive key -materials. There are three types of keys used by the key manager: the Secure -Storage Key (SSK), the TA Storage KEY (TSK) and the File Encryption Key (FEK). - -### Secure Storage Key (SSK) - -SSK is a per-device key and is generated and stored in secure memory when OP-TEE -is booting. SSK is used to derive the TA Storage Key (TSK). - -SSK is derived by: -> SSK = HMAC<sub>SHA256</sub> (HUK, Chip ID || "static string") - -The functions to get Hardware Unique Key (HUK) and chip ID depend on platform -implementation. - -Currently, in OP-TEE OS we only have a per-device key, SSK, which is used for -secure storage subsystem, but, for the future we might need to create different -per-device keys for different subsystems using the same algorithm as we -generate the SSK; An easy way to generate different per-device keys for -different subsystems is using different static strings to generate the keys. - -### Trusted Application Storage Key (TSK) - -The TSK is a per-Trusted Application key, which is generated from the SSK and -the TA's identifier (UUID). It is used to protect the FEK, in other words, -to encrypt/decrypt the FEK. - -TSK is derived by: -> TSK = HMAC<sub>SHA256</sub> (SSK, TA_UUID) - -### File Encryption Key (FEK) - -When a new TEE file is created, key manager will generate a new FEK by -PRNG (pesudo random number generator) for the TEE file and store the encrypted -FEK in meta file. FEK is used for encrypting/decrypting the TEE file information -stored in meta file or the data stored in block file. - -## Hash Tree - -The hash tree is responsible for handling data encryption and decryption of -a secure storage file. - -The hash tree is implemented as a binary tree where -each node (`struct tee_fs_htree_node_image` below) in the tree protects its -two child nodes and a data block. - -The meta data is stored in a header (`struct tee_fs_htree_image` below) -which also protects the top node. - -All fields (header, nodes, and blocks) are duplicated with two versions, 0 -and 1, to ensure atomic updates. See -[core/tee/fs_htree.c](../core/tee/fs_htree.c) for details. - -### Meta Data Encryption Flow - -![Meta Data Encryption](images/secure_storage/meta_data_encryption.png -"Meta data encryption") - -A new meta IV will be generated by PRNG when a meta data needs to be updated. -The size of meta IV is defined in -[core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h) - -The data structures of meta data and node data are defined in -[core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h) as follows: - -``` c -struct tee_fs_htree_node_image { - uint8_t hash[TEE_FS_HTREE_HASH_SIZE]; - uint8_t iv[TEE_FS_HTREE_IV_SIZE]; - uint8_t tag[TEE_FS_HTREE_TAG_SIZE]; - uint16_t flags; -}; - -struct tee_fs_htree_meta { - uint64_t length; -}; - -struct tee_fs_htree_imeta { - struct tee_fs_htree_meta meta; - uint32_t max_node_id; -}; - -struct tee_fs_htree_image { - uint8_t iv[TEE_FS_HTREE_IV_SIZE]; - uint8_t tag[TEE_FS_HTREE_TAG_SIZE]; - uint8_t enc_fek[TEE_FS_HTREE_FEK_SIZE]; - uint8_t imeta[sizeof(struct tee_fs_htree_imeta)]; - uint32_t counter; -}; -``` - -### Block Data Encryption Flow - -![Block Data Encryption](images/secure_storage/block_data_encryption.png -"Block data encryption") - -A new block IV will be generated by PRNG when a block data needs to be updated. -The size of block IV is defined in -[core/include/tee/fs_htree.h](../core/include/tee/fs_htree.h) - -## Atomic Operation - -According to GlobalPlatform Trusted Storage requirement of the atomicity, the -following operations should support atomic update: -> Write, Truncate, Rename, Create and Delete - -The strategy used in OP-TEE secure storage to guarantee the atomicity is -out-of-place update. - -## Important caveats - -Currently **no OP-TEE platform is able to support retrieval of the Hardware -Unique Key or Chip ID required for secure operation**. - -For all platforms, a constant key is used, resulting in no protection against -decryption, or Secure Storage duplication to other devices. - -This is because information about how to retrieve key data from the SoC is -considered sensitive by the vendors and it is not freely available. - -In OP-TEE, there are APIs for reading keys generically from -One-Time-Programmable (OTP) memory. But there are no existing platform -implementations. - -To allow Secure Storage to operate securely on your platform, you must define -implementations in your platform code for: - -``` c - TEE_Result tee_otp_get_hw_unique_key(struct tee_hw_unique_key *hwkey); - int tee_otp_get_die_id(uint8_t *buffer, size_t len); -``` - -These implementations should fetch the key data from your SoC-specific e-fuses, -or crypto unit according to the method defined by your SoC vendor. - -## Reference - -* [SFO15 Secure Storage (slides)](http://connect.linaro.org/resource/sfo15/sfo15-503-secure-storage-in-op-tee/) -* [LAS16 Secure Storage (slides)](http://connect.linaro.org/resource/las16/las16-504/) -* [SFO17 Secure Storage (slides)](http://connect.linaro.org/resource/sfo17/sfo17-309/) -* [TEE Internal Core API Specification v1.1](http://www.globalplatform.org/specificationsdevice.asp) diff --git a/documentation/secure_storage_rpmb.md b/documentation/secure_storage_rpmb.md deleted file mode 100644 index 60f6305c..00000000 --- a/documentation/secure_storage_rpmb.md +++ /dev/null @@ -1,147 +0,0 @@ -# RPMB Secure Storage - -## Introduction - -This document describes the RPMB secure storage implementation in OP-TEE, -which is enabled by setting CFG_RPMB_FS=y. Trusted Applications may use -this implementation by passing a storage ID equal to -TEE_STORAGE_PRIVATE_RPMB, or TEE_STORAGE_PRIVATE if CFG_REE_FS is disabled. -For details about RPMB, please refer to the JEDEC eMMC specification -[[1]](#JEDECeMMC). - -The architecture is depicted below. - -``` - NORMAL WORLD : SECURE WORLD - : - U tee-supplicant : Trusted application - S (rpmb.c) : (secure storage API) - E ^ ^ : ^ - R | | :~~~~~~~~~~~~~~~~~~|~~~~~~~~~~~~~~~~~~~~ - ~~~~~~~ ioctl ~~~~~~~|~~~~~~~~~~~~: v - K | | : OP-TEE - E v v : (tee_svc_storage.c) - R MMC/SD subsys. OP-TEE driver : (tee_rpmb_fs.c, tee_fs_key_manager.c) - N ^ ^ : ^ - E | | : | - L v | : | - Controller driver | : | - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~|~~~~~~~~~~~~~~~~~~~~~~~~|~~~~~~~~~~~~~~~~~~~~ - v v - Secure monitor / EL3 firmware -``` - -For information about the `ioctl()` interface to the MMC/SD subsystem in the -Linux kernel, see the Linux core MMC header file [[2]](#mmc-core-h) and the -mmc-utils repository [[3]](#mmc-utils). - -## The Secure Storage API - -This part is common with the REE-based filesystem. The interface between the -system calls in [core/tee/tee_svc_storage.c](../core/tee/tee_svc_storage.c) and -the RPMB filesystem is the **tee_file_operations** structure `tee_file_ops`. - -## The RPMB filesystem - -The FS implementation is entirely in -[core/tee/tee_rpmb_fs.c](../core/tee/tee_rpmb_fs.c). - -The RPMB partition is divided in three parts: - -- The first 128 bytes are reserved for partition data (struct -**rpmb_fs_partition**). -- At offset 512 is the File Allocation Table (FAT). It is an array of -struct **rpmb_fat_entry** elements, one per file. The FAT grows dynamically as -files are added to the filesystem. Among other things, each entry has the start -address for the file data, its size, and the filename. -- Starting from the end of the RPMB partition and extending downwards is the -file data area. - -Space in the partition is allocated by the general-purpose allocator functions: -`tee_mm_alloc()` and `tee_mm_alloc2()`. - -All file operations are atomic. This is achieved thanks to the following -properties: -- Writing one single block of data to the RPMB partition is guaranteed to be -atomic by the eMMC specification. -- The FAT block for the modified file is always updated last, after data have -been written successfully. -- Updates to file content is done in-place only if the data do not span more -than the "reliable write block count" blocks. Otherwise, or if the file needs -to be extended, a new file is created. - -## Device access - -There is no eMMC controller driver in OP-TEE. The device operations all have to -go through the normal world. They are handled by the `tee-supplicant` process -which further relies on the kernel's `ioctl()` interface to access the device. -`tee-supplicant` also has an emulation mode which implements a virtual RPMB -device for test purposes. - -RPMB operations are the following: -- Reading device information (partition size, reliable write block count) -- Programming the security key. This key is used for authentication purposes. -Note that it is different from the Secure Storage Key (SSK) defined below, which -is used for encryption. Like the SSK however, the security key is also derived -from a hardware unique key or identifier. Currently, the function -`tee_otp_get_hw_unique_key()` is used to generate the RPMB security key. -- Reading the write counter value. The write counter is used in the HMAC -computation during read and write requests. The value is read at initialization -time, and stored in the **tee_rpmb_ctx** structure, `rpmb_ctx->wr_cnt`. -- Reading or writing blocks of data - -RPMB operations are initiated on request from the FS layer. Memory buffers for -requests and responses are allocated in shared memory using -`thread_optee_rpc_alloc_payload()`. -Buffers are passed to the normal world in a `TEE_RPC_RPMB_CMD` message, thanks -to the `thread_rpc_cmd()` function. Most RPMB requests and responses use the -data frame format defined by the JEDEC eMMC specification. - -HMAC authentication is implemented here also. - -## Encryption - -The FS encryption routines are in [core/tee/tee_fs_key_manager.c](../core/tee/tee_fs_key_manager.c). - -Block encryption protects file data. The algorithm is 128-bit AES in Cipher Block Chaining -(CBC) mode with Encrypted Salt-Sector Initialization Vector (ESSIV) -[[4]](#CBC-ESSIV). - -- During OP-TEE initialization, a 128-bit AES Secure Storage Key (SSK) is -derived from a Hardware Unique Key (HUK). It is kept in secure memory and never -written to disk. A Trusted Application Storage Key is derived from the SSK and -the TA UUID. -- For each file, a 128-bit encrypted File Encryption Key (FEK) is randomly -generated when the file is created, encrypted with the TSK and stored in the FAT -entry for the file. -- Each 256-byte block of data is then encrypted in CBC mode. The initialization -vector is obtained by the ESSIV algorithm, that is, by encrypting the block -number with a hash of the FEK. This allows direct access to any block in the -file, as follows: -``` - FEK = AES-Decrypt(TSK, encrypted FEK); - k = SHA256(FEK); - IV = AES-Encrypt(128 bits of k, block index padded to 16 bytes) - Encrypted block = AES-CBC-Encrypt(FEK, IV, block data); - Decrypted block = AES-CBC-Decrypt(FEK, IV, encrypted block data); -``` - - -SSK, TSK and FEK handling is common with the REE-based secure storage, while the AES -CBC block encryption is used only for RPMB (the REE implementation uses GCM). - -The FAT is not encrypted. - -## REE FS - -If configured with both CFG_REE_FS=y and CFG_RPMB_FS=y the REE FS will -create a special file, "dirfile.db.hash" in RPMB which hold a hash -representing the state of REE FS. - -## References - -- <a name="JEDECeMMC"></a>[1] _Embedded Multi-Media Card (e•MMC) Electrical Standard (5.1)_, JEDEC JESD84-B51, February 2015 -- <a name="mmc-core-h"></a>[2] [linux/mmc/core.h](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/mmc/core.h), Linux kernel sources -- <a name="mmc-utils"></a>[3] The [mmc-utils](http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git) repository -- <a name="CBC-ESSIV"></a>[4] [_Cipher Block Chaining_](https://en.wikipedia.org/wiki/Disk_encryption_theory#Cipher-block_chaining_.28CBC.29), -Wikipedia diff --git a/documentation/virtualization.md b/documentation/virtualization.md deleted file mode 100644 index 77d1f3a5..00000000 --- a/documentation/virtualization.md +++ /dev/null @@ -1,191 +0,0 @@ -# Virtualization Support # - -## Overview ## - -OP-TEE have experimental virtualization support. This is when one -OP-TEE instance can run TAs from multiple virtual machines. OP-TEE -isolates all VM-related states, so one VM can't affect another in any -way. - -With virtualization support enabled, OP-TEE will rely on a hypervisor, -because only the hypervisor knows which VM is calling OP-TEE. Also, -naturally the hypervisor should inform OP-TEE about creation and -destruction of VMs. Besides, in almost all cases, hypervisor enables -two-stage MMU translation, so VMs does not see real physical address -of memory, instead they work with intermediate physical addresses -(IPAs). On other hand OP-TEE can't translate IPA to PA, so this is a -hypervisor's responsibility to do this kind of translation. So, -hypervisor should include a component that knows about OP-TEE protocol -internals and can do this translation. We call this component "TEE -mediator" and right now only XEN hypervisor have OP-TEE mediator. - -## Configuration ## - -Virtualization support is enabled with `CFG_VIRTUALIZATION` -configuration option. When this option is enabled, OP-TEE will **not** -work without compatible a hypervisor. This is because the hypervisor -should send `OPTEE_SMC_VM_CREATED` SMC with VM ID before any standard -SMC can be received from client. - -`CFG_VIRT_GUEST_COUNT` controls the maximum number of supported -VMs. As OP-TEE have limited size of available memory, increasing this -count will decrease amount of memory available to one VM. Because we -want VMs to be independent, OP-TEE splits available memory in equal -portions to every VM, so one VM can't consume all memory and cause DoS -to other VMs. - -## Requirements for hypervisor ## - -As said earlier, hypervisor should be aware of OP-TEE and SMCs from -virtual guests to OP-TEE. This is a list of things, that compatible -hypervisor should perform: - -1. When new OP-TEE-capable VM is created, hypervisor should inform - OP-TEE about it with SMC `OPTEE_SMC_VM_CREATED`. `a1` parameter should - contain VM id. ID 0 is defined as `HYP_CLNT_ID` and is reserved for - hypervisor itself. - -2. When OP-TEE-capable VM is being destroyed, hypervisor should stop - all VCPUs (this will ensure that OP-TEE have no active threads for - that VMs) and send SMC `OPTEE_SMC_VM_DESTROYED` with the same - parameters as for `OPTEE_SMC_VM_CREATED`. - -3. Any SMC to OP-TEE should have VM ID in `a7` parameter. This is - either `HYP_CLNT_ID` if call originates from hypervisor or VM ID - that was passed in `OPTEE_SMC_VM_CREATED` call. - -4. Hypervisor should perform IPA<->PA address translation for all - SMCs. This includes both arguments in `a1`-`a6` registers and in - in-memory command buffers. - -5. Hypervisor should pin memory pages that VM shares with OP-TEE. This - means, that hypervisor should ensure that pinned page will reside - at the original PA as long, as it is shared with OP-TEE. Also it - should still belong to the VM that shared it. For example, the - hypervisor should not swap out this page, transfer ownership to - another VM, unmap it from VM address space and so on. - -6. Naturally, the hypervisor should correctly handle the OP-TEE - protocol, so for any VM it should look like it is working with - OP-TEE directly. - -## Limitations ## - -Virtualization support is in experimental state and it have some -limitations, user should be aware of. - -### Platforms support ### - -Only Armv8 architecture is supported. There is no hard restriction, -but currently Armv7-specific code (like MMU or thread manipulation) -just know nothing about virtualization. - -Only one platform has been tested right now and that is QEMU-V8 (aka -qemu that emulates Arm Versatile Express with Armv8 architecture). - -Support for Rcar Gen3 should be added soon. - -### Static VMs guest count and memory allocation ### - -Currently, a user should configure maximum number of guests. OP-TEE will -split memory into equal chunks, so every VM will have the same amount of -memory. For example, if you have 6MB for your TAs, you can set -`CFG_VIRT_GUEST_COUNT` to 3 and every VM would be able to use 2MB -maximum, even if there is no other VMs running. - -This is okay for embedded setups when you know exact number and roles -of VMs, but can be inconvenient for server applications. - -Also, it is impossible to configure amount of memory available for a -given VM. Every VM instance will have exactly the same amount of memory. - -### Sharing hardware resources and PTAs ### - -Right now only HW that can be used by multiple VMs simultaneously is -serial console, used for logging. Devices like HW crypto accelerators, -secure storage devices (e.g. external flash storage, accessed directly -from OP-TEE) and others are not supported right now. Drivers -should be made virtualization-aware before they can be used with -virtualization extensions. - -Every VM will have own PTA states, which is a good thing in most -cases. But if one wants PTA to have some global state that is shared -between VMs, he need to write PTA accordingly. - -### No compatibility with "normal" mode ### - -OP-TEE built with `CFG_VIRTUALIZATION=y` will not work without -a hypervisor, because before executing any standard SMC, -`OPTEE_SMC_VM_CREATED` must be called. - -This can be inconvenient if one wants to switch between virtualized -and non-virtualized environment frequently. On other hand, it is not a -big deal in a production environment. - -Simple workaround can be made for this: if OP-TEE receives standard -SMC prior to `OPTEE_SMC_VM_CREATED`, it implicitly creates VM context -and uses it for all subsequent calls. - -## Implementation details ## - -OP-TEE as a whole can be split into two entities. Let us call them -"nexus" and TEE. Nexus is a core part of OP-TEE that takes care of low -level things: SMC handling, memory management, threads creation and so -on. TEE is a part that does the actual job: handles requests, loads -TAs, executes them, and so on. - -So, it is natural to have one nexus instance and multiple instances of -TEE, one TEE instance per registered VM. This can be done either -explicitly or implicitly. - -Explicit way is to move TEE state in some sort of structure and make -all code to access fields of this structure. Something like `struct -task_struct` and `current` in linux kernel. Then it is easy to -allocate such structure for every VM instance. But this approach -basically requires to rewrite all OP-TEE code. - -Implicit way is to have banked memory sections for TEE/VM instances. -So memory layout can look something like that: - - +-------------------------------------------------+ - | Nexus: .nex_bss, .nex_data, ... | - +-------------------------------------------------+ - | TEE states | - | | - | VM1 TEE state | VM 2 TEE state | VM 3 TEE state | - | .bss, .data | .bss, .data | .bss, .data, | - +-------------------------------------------------+ - -This approach requires no changes in TEE code and requires some -changes into nexus code. So, idea that Nexus state resides in separate -sections (`.nex_data`, `.nex_bss`, `.nex_nozi`, `.nex_heap` and -others) and is always mapped. - -TEE state resides in standard sections (like `.data`, `.bss`, `.heap` -and so on). There is a separate set of this sections for every VM -registered and Nexus maps them only when it receives call from -corresponding VM. - -As Nexus and TEE have separate heaps, `bget` allocator was extended to -work with multiple "contexts". `malloc()`, `free()` with friends work -with one context. `nex_malloc()` (and other `nex_` functions) were -added. They use different context, so now Nexus can use separate heap, -which is always mapped into OP-TEE address space. When virtualization -support is disabled, all those `nex_` functions are defined to point -to standard `malloc()` counterparts. - -To change memory mappings in run-time, in MMU code we have added a new -entity, named "partition", which is defined by `struct -mmu_partition`. It holds information about all page-tables, so the whole -MMU mapping can be switched by one write to `TTBR` register. - -There is the default partition, it holds MMU state when there is no VM -context active, so no TEE state is mapped. When OP-TEE receives -`OPTEE_SMC_VM_CREATED` call, it copies default partition into new one -and then maps sections with TEE data. This is done by -`prepare_memory_map()` function in `virtualization.c`. - -When OP-TEE receives STD call it checks that the supplied VM ID is -valid and then activates corresponding MMU partition, so TEE code can -access its own data. This is basically how virtualization support is -working. |
