blob: 63ea8fc5b01b18f893f6a9f92e0619295c866d9a [file] [log] [blame]
Joakim Bech8e5c5b32018-10-25 08:18:32 +02001.. _faq:
2
3##########################
4Frequently Asked Questions
5##########################
6
7.. contents:: Table of Contents
8
9----
10
11Abbreviations
12*************
13:OP-TEE: Open Portable TEE
14:TA: Trusted Application
15:TEE: Trusted Execution Environment
16:TZASC: TrustZone Address Space Controller
17:TZPC: TrustZone Protection Controller
18
19----
20
21Architecture
22************
23Q: Which platforms/architectures are supported?
24===============================================
25 - The :ref:`platforms_supported` page lists all platforms and architectures
26 currently supported in the official tree.
27
28Q: Are 32-bit as well as 64-bit support?
29========================================
30 - Both 32- and 64-bit are fully supported for all OP-TEE components.
31
32Q: Does OP-TEE support mixed-mode, i.e., both AArch32 and AArch64 Trusted Applications on top of an AArch64 core?
33=================================================================================================================
34 - Yes!
35
36Q: Whats the maximum size for heap and stack? Can it be changed?
37=================================================================
38 - Yes, it can be changed. In the current setup (for vexpress for example),
39 there are ``32MB DDR`` dedicated for OP-TEE. ``1MB`` for ``TEE RAM`` and
40 ``1MB`` for ``PUB RAM``, this leaves ``30MB`` for Trusted Applications. In
41 the Trusted Applications, you set ``TA_STACK_SIZE`` and ``TA_DATA_SIZE``.
42 Typically, we set stack to ``2KB`` and data to ``32K``. But you are free
43 to adjust those according to the amount of memory you have available. If
44 you need them to be bigger than ``1MB`` then you also must adjust TAs MMU
45 L1 table accordingly, since default section mapping is 1MB.
46
47Q: What is the size of OP-TEE itself?
48=====================================
49 - As of 2016.01, optee_os is about ``244KB`` (release build). It is
50 preferred to run :ref:`optee_os` entierly in SRAM, but if there is not
51 enough room, DRAM can be used and protected with TZASC. We are also
52 looking into the possibility of creating a minimal OP-TEE, i.e. a
53 limited OP-TEE usable even in a very memory constrained environment, by
54 eliminating as many memory-hungry parts as possible. There is however no
55 ETA for this at the moment.
56
57 - You can check the memory usage by using the ``make mem_usage`` target in
58 :ref:`optee_os`, for example:
59
60 .. code-block:: bash
61
62 $ make ... mem_usage
63 # Which will output a file with the figures here:
64 # out/arm/core/tee.mem_usage
65
66 You will of course get different sizes depending on what compile time
67 flags you have enabled when running `make mem_usage`.
68
69Q: Can NEON optimizations be done in OP-TEE?
70============================================
71 - Yes (for additional information, please also see `Issue#953`_)
72
73Q: Can I use C++ libraries in OP-TEE?
74=====================================
75 - C++ libraries are currently not supported. Technically, it is possible but
76 will require a fair amount of work to implement, especially more so if
77 exceptions are required. There are currently no plans to do this.
78
79 - See `Issue#2628`_ for related information.
80
81Q: Would using `malloc()` in OP-TEE give physically contiguous memory?
82======================================================================
83 - ``malloc()`` in OP-TEE currently gives physically contiguous memory. It is
84 not guaranteed as it is not mentioned anywhere in the documentation, but
85 in practice the heap only has physically contiguous memory in the pool(s).
86 The heap in OP-TEE is normally quite small, ~24KiB, and could be a bit
87 fragmented.
88
89Q: Can I limit what CPUs / cores OP-TEE runs on?
90================================================
91 - Currently its up to the kernel to decide which core it runs on, i.e, it
92 will be the same core as the one initiating the SMC in Linux. Please also
93 see `Issue#1194`_.
94
95Q: How is OP-TEE being scheduled?
96=================================
97 - OP-TEE does not have its own scheduler, instead it is being scheduled by
98 Linux kernel. For more information, please see `Issue#1036` and
99 `Issue#1183`_.
100
101----
102
103Board support
104*************
105Q: How do I port OP-TEE to another platform?
106============================================
107 - Start by reading the :ref:`porting_guidelines`.
108
109 - See the :ref:`presentations` page. There might be some interesting
110 information in the "LCU14-302 How To Port OP-TEE To Another Platform" deck
111 and video. Beware that the presentation is more than five years old, so
112 even though it is a good source, there might be parts that are not
113 relevant any longer.
114
115 - As a good example for
116
117 - **Armv8-A** patch enabling OP-TEE support on a new device, please see
118 the `ZynqMP port`_ that enabled support for running OP-TEE on `Xilinx
119 UltraScale+ Zynq MPSoC`. Besides that there are similar patches for
120 `Juno port`_, `Raspberry Pi3 port`_, `HiKey port`_.
121
122 - **ARMv7-A**, please have a look at the `Freescale ls1021a port`_,
123 another example would be the `TI DRA7xx port`_.
124
125----
126
127Building
128********
129Q: I got build errors running latest, why?
130==========================================
131 - What did you try to build? Only :ref:`optee_os`? A full OP-TEE developer
132 setup using QEMU, HiKey, RPi3, Juno using repo? AOSP? OpenEmbedded? What
133 we build on daily basis are the OP-TEE developer setups (see
134 :ref:`optee_developer_setup`) , but other builds like AOSP and
135 OpenEmbedded are builds that we try from time to time, but not very often
136 within Security Working Group. Having that said there are other teams in
137 Linaro working with such builds, but they most often base their builds on
138 OP-TEE stable releases.
139
140 - By running latest instead of stable also comes with a risk of getting
141 build errors due to version and/or interdependency skew which can result
142 in build error. Now, such issues most often affects running xtest and not
143 the building. If you however clean all gits and do a ``repo sync -d``. Then
144 we're almost 100% sure you will get back to a working state again, since
145 as mentioned in next bullet, we build (and run xtest) on all QEMU on all
146 patches sent to OP-TEE.
147
148 - Every pull request in OP-TEE are tested on hardware (see
149 :ref:`how_are_you_testing_optee`).
150
151Q: I got build errors running stable tag x.y.z, why?
152====================================================
153 - Stable releases are quite well tested both in terms of building for all
154 supported platforms and running xtest on all platforms, so if you cannot
155 get that to build and run, then there is a great chance you have something
156 wrong on your side. All platforms that has been tested on a stable release
157 can be found in `CHANGELOG.md`_ file. Having that said, we do make mistakes
158 on stable builds also from time to time.
159
160Q: I get `gcc XYZ` or `g++ XYZ` compiler error messages?
161========================================================
162 - Most likely you're trying to build OP-TEE using the regular x86 compiler
163 and not the using the Arm toolchain. Please install the
164 :ref:`prerequisites` and make sure you have gotten and installed the Arm
165 toolchains as described at the :ref:`toolchains` page. (for additional
166 information, please see `Issue#846`_).
167
168Q: I found this build.git, what is that?
169========================================
170 - :ref:`build` is a git that is used in conjunction with the
171 :ref:`manifest` to create full OP-TEE developer builds. It contains
172 helper makefiles that makes it easy to get OP-TEE up and running on the
173 setups that are using repo.
174
175Q: When running `make` from build.git it fails to download the toolchains?
176==========================================================================
177- We try to stay somewhat up to date with running recent ``GCC`` versions. But
178 just like everywhere else on the net things moves around. In some cases like
179 `Issue#1195`_, the URL was changed without us noticing it. If you find and fix
180 such an issue, please send the fix as pull request and we will be happy to
181 merge it.
182
Jerome Forissier07e7fa02020-01-22 08:39:03 +0100183.. _faq_try_optee:
184
Joakim Bech8e5c5b32018-10-25 08:18:32 +0200185Q: What is the quickest and easiest way to try OP-TEE?
186======================================================
187 - That would be running it on QEMU on a local PC. To do that you would need to:
188
189 - Install the OP-TEE :ref:`prerequisites`.
190 - Build for QEMU according to the instructions at :ref:`qemu_v7`.
191 - And :ref:`optee_test_run_xtest`.
192
193 - By summarizing the above, you would need to:
194 .. code-block:: bash
195
196 $ sudo apt-get install [pre-reqs]
197 $ mkdir optee-qemu && cd optee-qemu
198 $ repo init -u https://github.com/OP-TEE/manifest.git
199 $ repo sync
200 $ cd build
201 $ make toolchains -j2
202 $ make run
203 QEMU console: (qemu) c
204 Normal world shell: # xtest
205
206----
207
208Certification and security reviews
209**********************************
210Q: Will linaro be involved in GlobalPlatform certification/qualification?
211=========================================================================
212 - No we will not, mainly for two reasons. The first is that there was a
213 board decision that Security WG in Linaro should not be part of
214 certifications. The second reason is that most often certification is done
215 using a certain software version and on a unique device. I.e., it is the
216 combination software + hardware that gets certified. Since Linaro have no
217 own devices in production or for sale, we cannot be part of any
218 certification. This is typically something that the SoC or OEM needs to
219 do.
220
221 - But it is worth mentioning that since OP-TEE is coming from a proprietary
222 TEE solution that was GlobalPlatform certified on some products in the
223 past and we regularly have people from some member companies running the
224 extended test suite from GlobalPlatform we know that the gap to become
225 GlobalPlatform certified/qualified isnt that big.
226
227.. _q_has_any_test_lab_been_testing_op-tee:
228
229Q: Has any test lab been testing OP-TEE?
230========================================
231 - `Applus Laboratories`_ have done some side-channel attack testing and
232 fault injection testing on OP-TEE using the :ref:`hikey` device. Their
233 findings and fixes can be found at the `Security Advisories`_ page at
234 optee.org.
235
236 - Riscure_ did a mini-audit of OP-TEE which generated a couple of patches
237 (see `PR#2745`). The `Security Advisories`_ page at optee.org will be
238 updated with more information regarding that in the future.
239
240
241Q: Have there been any code audit / code review done?
242=====================================================
243 - Full audit? No! Not something initiated by Linaro. But there has been some
244 companies that have done audits internally and they have then shared the
245 result with us and where relevant, we have created patches resolving the
246 issues reported to us (see :ref:`q_has_any_test_lab_been_testing_op-tee`).
247
248 - Code review, yes! Every single patch going into OP-TEE has been reviewed
249 in a pull request on GitHub. We more or less have a requirement that every
250 patch going into OP-TEE shall at least have one "Reviewed-by" tag in the
251 patch.
252
253 - Third party / test lab code review, no! Again some companies have reviewed
254 internally and shared the result with us, but other than that no (see
255 related :ref:`q_has_any_test_lab_been_testing_op-tee`)
256
257
258Contribution
259************
260Q: How do I contribute?
261=======================
262 - Please see the :ref:`contribute` page.
263
264Q: Where can I get help?
265========================
266 - Please see the :ref:`contact` page.
267
268Q: I'm new to OP-TEE but I would like to help out, what can I do?
269=================================================================
270 - We always need help with code reviews, feel free to review any of the open
271 `OP-TEE OS Pull Requests`_. Please also note that there could be open pull
272 request in the other :ref:`optee_gits` that needs reviews too.
273
274 - We always need help answering all the questions asked at `OP-TEE OS
275 Issues`_.
276
277 - If you want to try to solve a bug, please have a look at the `OP-TEE OS
278 Bugs`_ or the `OP-TEE OS Enhancements`_.
279
280 - Documentation tends to become obsolete if not maintained on regular basis.
281 We try to do our best, but we're not perfect. Please have a look at
282 :ref:`optee_docs` and try to update where you find gaps.
283
284 - Enable `repo` for the device in :ref:`manifest` and :ref:`build` (and also
285 :ref:`platforms_supported`) currently not using repo.
286
287 - If you would like to implement a bigger feature, please reach out to us
288 (see :ref:`contact`) and we can discuss what is most relevant to look into
289 for the moment. If you already have an idea, feel free to send the
290 proposal to us.
291
292----
293
294Interfaces
295**********
296Q: Which APIs have been implemented in OP-TEE?
297===============================================
298 - GlobalPlatform (see :ref:`globalplatform_api` for more details).
299 - GlobalPlatform's TEE Client API v1.1 specification
300 - GlobalPlatform's TEE Internal Core API v1.1 specification.
301 - GlobalPlatform's Secure Elements v1.0 (**now deprecated**, see ``git
302 log``).
303 - GlobalPlatform's Socket API v1.0 (TCP and UDP, but not TLS).
304
305 - AOSP Keymaster_ (v3) and AOSP Gatekeeper_ (see :ref:`aosp` for more
306 details).
307
308 - `Android Verified Boot 2.0`_ (AVB 2.0)
309
310----
311
312Hardware and peripherals
313************************
314Q: Can I use my own hardware IP for crypto acceleration?
315========================================================
316 - Yes, OP-TEE has a Crypto Abstraction Layer (see
317 :ref:`cryptographic_implementation` that was designed mainly to make it
318 easy to add support for hardware crypto acceleration. There you will find
319 information about the abstraction layer itself and what you need to do to
320 be able to support new software/hardware drivers in OP-TEE.
321
322----
323
324License
325*******
326Q: Under what license is OP-TEE released?
327=========================================
328 - The software is mostly provided under the `BSD 2-Clause`_ license.
329
330 - The TEE kernel driver is released under GPLv2 for obvious reasons.
331
332 - xtest (:ref:`optee_test`) uses BSD 2-Clause for code running in secure
333 world (Trusted Applications etc) and GPLv2 for code running in normal
334 world (client code).
335
336Q: GlobalPlatform click-through license
337=======================================
338 - Since OP-TEE is a GlobalPlatform based TEE which implements the APIs as
339 specified by GlobalPlatform one has to accept, the click-through license
340 which is presented when trying to download the :ref:`globalplatform_api`
341 specifications before start using OP-TEE.
342
343Q: I've modified OP-TEE by using code with non BSD 2-Clause license, will you accept it?
344========================================================================================
345 - That is something we deal with case by case. But as a general answer, if
346 it does not contaminate the BSD 2-Clause license we will accept it. Reach
347 out to us (see :ref:`contact`) and we will take it from there.
348
349----
350
351Promotion
352*********
353Q: I want to get my company logo on op-tee.org, how?
354====================================================
355 - If your company has done significant contributions to OP-TEE, then please
356 :ref:`contact` us and we will do our best to include your company. Pay
357 attention to that we will review this on regular basis and inactive
358 supporting companies might be removed in the future again.
359
360----
361
362Security vulnerabilities
363************************
364Q: I have a found a security flaw in OP-TEE, how can I disclose it with you?
365============================================================================
366 - Please see the :ref:`Contact` page and the :ref:`disclosure_policy` page.
367
368----
369
370Source code
371***********
372Q: Where is the source code?
373============================
374 - It is located on GitHub under the project `OP-TEE`_ and `linaro-swg`_.
375
376Q: Where do I download the test suite called xtest?
377===================================================
378 - All the source code for that can be found in the git called
379 :ref:`optee_test`.
380
381 - The :ref:`globalplatform_tests` can be purchased separately.
382
383Q: Where is the Linux kernel TEE driver?
384========================================
385 - You can find both the generic TEE framework including the OP-TEE driver
386 included in the official Linux kernel project since v4.12. Having that
387 said, we "buffer up" pending patches on a our :ref:`linux_kernel` branch.
388 I.e., that is where we keep new features being developed for OP-TEE. In
389 the long run we aim to completely stop using our own branch and just send
390 all patches to the official Linux kernel tree directly. But as of now we
391 cannot do that.
392
393----
394
395Testing
396*******
397
398.. _how_are_you_testing_optee:
399
400Q: How are you testing OP-TEE?
401==============================
402 - There is a test suite called xtest that tests the complete TEE-solution to
403 ensure that the communication between all architectural layers is working
404 as it should. The test suite also tests the majority of the GlobalPlatform
405 TEE Internal Core API. It has close to 50,000 and ever increasing test
406 cases, and is also extendable to include the official GlobalPlatform test
407 suite (see :ref:`globalplatform_tests`).
408
409 - Every pull request in OP-TEE are built for a multitude of different platforms
410 automatically using Travis_, Shippable_ and IBART_. Please have a look
411 there to see whether it failed building on the platform you're using
412 before submitting any issue about build errors.
413
414 - For more information see :ref:`optee_test`.
415
416----
417
418Trusted Applications
419********************
420Q: How do I write a Trusted Application (TA)?
421=============================================
422 - Have a look at the :ref:`build_trusted_applications` page as well as the
423 :ref:`optee_examples` page. Those provides guidelines and examples on how
424 to implement basic Trusted Applications.
425
426 - If you want to see more advanced uses cases of Trusted Applications, then
427 we encourage that you have a look at the Trusted Applications
428 :ref:`optee_test`.
429
430Q: How do I link a library into a Trusted Application?
431======================================================
432 - See the example in :ref:`build_trusted_applications_submk`.
433
434 - Also see `Issue#280`_, `Issue#601`_, `Issue#901`_, `Issue#1003`_.
435
436Q: Where should I put my compiled Trusted Application on the device?
437====================================================================
438 - ``/lib/optee_armtz``, that is the default location where tee-supplicant
439 will look for Trusted Applications.
440
441.. _what_is_a_psuedo_ta_and_how_do_i_write_one:
442
443Q: What is a Psuedo TA and how do I write one?
444==============================================
445 - A Psuedo TA is an OP-TEE firmware service offered through the generic API
446 used to invoke Trusted Applications. Pseudo TA interface and services all
447 runs in TEE kernel / core context. I.e., it will have access to the same
448 functions, memory and hardware etc as the TEE core itself. If we're
449 talking ARMv8-A it is running in ``S-EL1``.
450
451Q: Are Psuedo **user space** TAs supported?
452===========================================
453 - No!
454
455Q: Can a static TA Open/Invoke dynamic TA?
456==========================================
457 - Yes, for a longer discussion see `Issue#967`_, `Issue#1085`_,
458 `Issue#1132`_.
459
460Q: How can I extend the GlobalPlatform Internal Core API?
461=========================================================
462 - You may develop your own “Psuedo TA”, which is part of the core (see
463 :ref:`what_is_a_psuedo_ta_and_how_do_i_write_one` for more information
464 about the Psuedo TA).
465
466Q: How are Trusted Applications verified?
467=========================================
468 - Please see the section :ref:`core_pub_priv_keypair` in the
469 :ref:`porting_guidelines`.
470
471 - Alternatively one can also build a Trusted Application and embed its raw
472 binary content into the OP-TEE firmware binary. At runtime, if invoked,
473 the Trusted Application will be loaded from the OP-TEE firmware image
474 instead of being fetched from the normal world and authenticated in the
475 secure world (see :ref:`early_ta` for more information).
476
477Q: Is multi-core TA supported?
478==============================
479 - Yes, you can have two or more TAs running simultaneously. Please see also
480 `Issue#1194`_.
481
482Q: Is multi-threading supported in a TA?
483========================================
484 - No, there is no such concept as ``pthreads`` or similar. I.e, you cannot
485 spawn thread from a TA. If you need to run tasks in parallel, then you
486 should probably look into running two TAs or more simultaneously and then
487 let them communicate with each other using the ``TA2TA`` interface.
488
489Q: How can I use or call OP-TEE from native Android (apk) applications?
490=======================================================================
491 - Use the `Java Native Interface`_ (JNI).
492 - First get familiar with `sample_hellojni.html`_ and make sure you can run
493 the sample. After that, replace the C-side Implementation with for example
494 :ref:`hello_world` or one of the other examples in :ref:`optee_examples`.
495
496 .. note::
497
498 Note that :ref:`hello_world` and other binaries in optee_examples are built
499 as executables, and have to be modified to be built as a .so shared library
500 instead so that it can be loaded by the Java-side Implementation.
501
502 - Note that ``*.apk`` apps by default have no access to the TEE driver. See
503 `Issue#903`_ for details. The workaround is to disable SELinux before
504 launching any ``*.apk`` app that calls into OP-TEE. The solution is to
505 create/write SELinux domains/rules to allow any required access, but since
506 this is not a TEE-related issue, it is left as an exercise for the users.
507
508Q: I've heard that there is a Widevine and PlayReady TA, how do I get access?
509=============================================================================
510 - Those can only be shared are under WMLA and NDA/MLA with Google and
511 Microsoft. Linaro can help members of Linaro to get access to those. As of
512 now, we cannot share it with non-members.
513
514.. _Issue#280: https://github.com/OP-TEE/optee_os/issues/280
515.. _Issue#601: https://github.com/OP-TEE/optee_os/issues/601
516.. _Issue#846: https://github.com/OP-TEE/optee_os/issues/846
517.. _Issue#901: https://github.com/OP-TEE/optee_os/issues/901
518.. _Issue#903: https://github.com/OP-TEE/optee_os/issues/903
519.. _Issue#953: https://github.com/OP-TEE/optee_os/issues/953
520.. _Issue#967: https://github.com/OP-TEE/optee_os/issues/967
521.. _Issue#1003: https://github.com/OP-TEE/optee_os/issues/1003
522.. _Issue#1036: https://github.com/OP-TEE/optee_os/issues/1036
523.. _Issue#1085: https://github.com/OP-TEE/optee_os/issues/1085
524.. _Issue#1132: https://github.com/OP-TEE/optee_os/issues/1132
525.. _Issue#1183: https://github.com/OP-TEE/optee_os/issues/1183
526.. _Issue#1194: https://github.com/OP-TEE/optee_os/issues/1194
527.. _Issue#1195: https://github.com/OP-TEE/optee_os/issues/1195
528.. _Issue#2628: https://github.com/OP-TEE/optee_os/issues/2628
529
530.. _PR#2745: https://github.com/OP-TEE/optee_os/pull/2745
531
532.. _Android Verified Boot 2.0: https://android.googlesource.com/platform/external/avb/+/master/README.md
533.. _Applus Laboratories: http://www.appluslaboratories.com/en/
534.. _BSD 2-Clause: http://opensource.org/licenses/BSD-2-Clause
535.. _CHANGELOG.md: https://github.com/OP-TEE/optee_os/blob/master/CHANGELOG.md
536.. _Freescale ls1021a port: https://github.com/OP-TEE/optee_os/commit/85278139a8f914dddb36808861c86a472ecb0271
537.. _Gatekeeper: https://source.android.com/security/authentication/gatekeeper
538.. _HiKey port: https://github.com/OP-TEE/optee_os/commit/d70e78c49fc9c63b2d37c596b7ad3cbd38f8e574
539.. _IBART: https://optee.mooo.com:5000
540.. _Java Native Interface: http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html
541.. _Juno port: https://github.com/OP-TEE/optee_os/commit/90e7497e0480892e2c262cec64e6c47242d4db7f
542.. _Keymaster: https://source.android.com/security/keystore
543.. _linaro-swg: https://github.com/linaro-swg
544.. _OP-TEE: https://github.com/OP-TEE
545.. _OP-TEE OS Bugs: https://github.com/OP-TEE/optee_os/labels/bug
546.. _OP-TEE OS Enhancements: https://github.com/OP-TEE/optee_os/labels/enhancement
547.. _OP-TEE OS Issues: https://github.com/OP-TEE/optee_os/issues
548.. _OP-TEE OS Pull Requests: https://github.com/OP-TEE/optee_os/pulls
549.. _Raspberry Pi3 port: https://github.com/OP-TEE/optee_os/commit/66d9cacf37e6bd4b0d86e7b32e4e5edefe8decfd
550.. _Riscure: https://www.riscure.com
551.. _sample_hellojni.html: https://developer.android.com/ndk/samples/sample_hellojni.html
552.. _Security Advisories: https://www.op-tee.org/security-advisories/
553.. _Shippable: https://app.shippable.com/github/OP-TEE/optee_os/dashboard
554.. _TI DRA7xx port: https://github.com/OP-TEE/optee_os/commit/9b5060cd92a19b4d114a1ce8a338b18424974037
555.. _Travis: https://travis-ci.org/OP-TEE
556.. _ZynqMP port: https://github.com/OP-TEE/optee_os/commit/dc57f5a0e8f3b502fc958bc64a5ec0b0f46ef11a