Difference between revisions of "How to build TEE for Android"

[quality revision] [quality revision]
(Prerequisites)
m (Integrate Trusted Applications)
 

This article explains how to build TEE components, except the OP-TEE drivers. The latter are part of the Linux build process and are compiled as loadable modules, please refer to How to build kernel for Android. It is intended for Distribution Package users.

The OP-TEE Security feature is composed of several parts:

  • OP-TEE drivers: included in the Linux Kernel
  • OP-TEE OS: part of bootloader image.
  • OP-TEE Client: the OP-TEE userland client and is part of the STM32MPU distribution for Android™.
  • OP-TEE Tests: OP-TEE Tests suite with dedicated trusted applications part of the STM32MPU distribution for Android™.
    • This module proposes a tests suite for OP-TEE
    • Only available when NOT in user building profile

For detail, you can refer to OP-TEE overview page.

1 Prerequisites[edit]

The environment must be installed using the distribution package adapted to the selected microprocessor device. See the list of supported Android Distribution Package.

To be able to execute the following instructions, work from the distribution root directory, initialize the environment and then run lunch:

 source build/envsetup.sh
 bspsetup
 lunch aosp_<BoardId>-userdebug
Info white.png Information
The bspsetup instruction needs to be run only once for the distribution

2 Partition layout[edit]

The OP-TEE OS is separated in three different partitions teeh, teed and teex to allow page management.

The OP-TEE TA (Trusted Applications) are integrated in the vendor partition.

The binaries are available in device/stm/<STM32Series>-tee/prebuilt.

Info white.png Information

For more information on the complete partition layout depending on your development platform, refer to the corresponding Flash mapping article named Your_development_platform Flash mapping for Android. Example: STM32MP15 Flash mapping for Android for the STM32MP15 boards.

All Flash mapping for Android articles belong to the Category:Flash mapping for Android.

3 Load the TEE sources[edit]

By default, the OP-TEE sources are not part of the STM32MPU distribution for Android™. To load the sources, execute the following instruction:

 load_tee
Info white.png Information

The load_tee script uses the configuration file android_opteeos.config located in the device/stm/<STM32Series>-tee/source/patch/optee-<version>/directory.

The loaded sources can then be accessed at the device/stm/<STM32Series>-tee/optee_os-<STM32Series> directory.

Info white.png Information

By default, only the archive is loaded from the remote repository (reducing size). If required you can clone the remote repository if all the git history is needed.

For this purpose, replace the android_opteeos.config file TEE_ARCHIVE_PATH by TEE_GIT_PATH. Then execute load_tee again (with -f option to replace previously loaded source).

4 Build the TEE[edit]

After retrieving the OP-TEE sources, build them using:

 build_tee

This instruction generates an OP-TEE for every available board. To generate an OP-TEE for one board:

 build_tee --boardb <BoardId>


or To get back more details on available options, run:

 build_tee --currenth

For more information check the instruction definitionsHere after, see the result for the version 1.3:


build_tee -h

Usage: build_tee [Options] [Board] [Command]

  This script buildsallows building the OP-TEE OS source

Options:
  -h / --help: print this message
  -i / --install: update prebuilt images
  -r <level> / --rpmb=<level>:
      0: disable RPMB (default)
      1: enable RPMB with TESTKEY for anti-rollback only (TAKE CARE: CFG_RPMB_WRITE_KEY is enabled, fusing the TESTKEY on your device)
      2: enable RPMB with TESTKEY for secure storage (TAKE CARE: CFG_RPMB_WRITE_KEY is enabled, fusing the TESTKEY on your device)
  -v / --version: get script version
  --verbose =<level>: enable build verbosity
(1 or 2 depending on level of0: no verbosity required(default)
 Board     1: Optionalremove (defaultscript =filtering
all)   -c/--current: build only for current configuration (board and memory)
  or
  -b/--board    2: remove script filtering and quiet option for the build
  -d <level> / --debug=<level>: TEE debug level
      0: no debug (default)
      1: TEE core and TA log level 2
      2: TEE core and TA log level 3)
  -b <name> / --board=<name>: set board name from following list = eval or disco(default: all)

Command: Optional, only one instructioncommand is supported at a time supported
  clean: execute make clean on targeted module

5 Integrate the TEE[edit]

To integrate the new OP-TEE solution within your distribution, first the prebuilt images have to be updated:

 build_tee -i

Then build the full distribution

 make -j

Finally, update the associated partitions for the device. Refer to Flashing the built image

6 Build Trusted Applications[edit]

Customize trusted applications can be built as needed. For this purpose, the configuration fileandroid_tabuild.config located in device/stm/<STM32Series>-tee/source has to be changed.

To build trusted applications, execute:

 build_ta

This script generates every applications for all available boards. To generate an application for one board only:

 build_ta --boardb <BoardId>

or To get back more details on available options, run:

 build_ta --currenth

For more information check the instruction definitionHere after, see the result for the version 1.1:


build_ta -h

Usage: build_ta [Options] [Board options]

  This script buildsallows building the trust applications (TA) source listed in android_tabuild.config file

Options:
  -h / --help: print this message
  -i / --install: update prebuilt images
  -v / --version: get script version
  --verbose =<level>: enable verbosity (1 or 2 depending on level of verbosity required)
 Board options:-b <name>  -c/--current: build only for current configuration (board and memory)
  or
  -b/--board =<name>: set board name from following list = eval or disco (default: all)

7 Integrate Trusted Applications[edit]

To integrate the new trusted applications into a distribution, first update the prebuilt images:

 build_ta -i

Then update the file device.mk copying the trusted application in the /vendor/lib/optee_armtz directory.

PRODUCT_COPY_FILES += \
	device/stm/
{{HighlightParam|''
<STM32Series>
''}}
-tee/prebuilt/
{{HighlightParam|''
<BoardId>
''}}
/ta/
{{HighlightParam|''
<UUID>
''}}
.ta:$(TARGET_COPY_OUT_VENDOR)/lib/optee_armtz/
{{HighlightParam|''
<UUID>
''}}
.ta

Next build the full distribution

 make -j

Finally, update the associated partitions on the device. Refer to How to populate boards for Android


This article explains how to build TEE components, except the OP-TEE drivers. The latter are part of the Linux build process and are compiled as loadable modules, please refer to [[How to build kernel for Android]]. It is intended for Distribution Package users.

The OP-TEE Security feature is composed of several parts:

*OP-TEE drivers: included in the Linux Kernel
*OP-TEE OS: part of bootloader image.
*OP-TEE Client: the OP-TEE userland client and is part of the [[STM32MPU distribution for Android]]&trade;.
*OP-TEE Tests: OP-TEE Tests suite with dedicated trusted applications part of the [[STM32MPU distribution for Android]]&trade;.
** This module proposes a tests suite for OP-TEE
** Only available when NOT in user building profile

For detail, you can refer to [[OP-TEE overview]] page.

== Prerequisites ==

The environment must be installed using the distribution package adapted to the selected microprocessor device.
See the list of supported Android [[Which_STM32MPU_Embedded_Software_Package_for_Android_better_suits_your_needs#Distribution_Package | Distribution Package]].

To be able to execute the following instructions, work from the distribution root directory, initialize the environment and then run <code>lunch</code>:

 {{PC$}} source build/envsetup.sh
 {{PC$}} bspsetup
 {{PC$}} lunch aosp_{{HighlightParam|''<BoardId>''}}-userdebug
{{Info| The <code>bspsetup</code> instruction needs to be run only once for the distribution}}

== Partition layout ==

The OP-TEE OS is separated in three different partitions <code>teeh</code>, <code>teed</code> and <code>teex</code> to allow page management.

The OP-TEE TA (Trusted Applications) are integrated in the <code>vendor</code> partition.

The binaries are available in <code>device/stm/{{HighlightParam|''<STM32Series>''}}-tee/prebuilt</code>.

{{Info|
For more information on the complete partition layout depending on your development platform, refer to the corresponding Flash mapping article named '''''Your_development_platform'' Flash mapping for Android'''. 
Example: [[STM32MP15 Flash mapping for Android]] for the STM32MP15 boards.

All ''Flash mapping for Android'' articles belong to the [[:Category:Flash mapping for Android]].
}}
== Load the TEE sources ==
By default, the OP-TEE sources are not part of the ''STM32MPU distribution for Android&trade;. To load the sources, execute the following instruction:

 {{PC$}} load_tee

{{Info |
The '''load_tee''' script uses the configuration file <code>android_opteeos.config</code> located in the <code>device/stm/{{HighlightParam|''<STM32Series>''}}-tee/source/patch/optee-{{HighlightParam|''<version>''}}/</code>directory.
}}

The loaded sources can then be accessed at the <code>device/stm/{{HighlightParam|''<STM32Series>''}}-tee/optee_os-{{HighlightParam|''<STM32Series>''}}</code> directory.

{{Info |
By default, only the archive is loaded from the remote repository (reducing size). If required you can clone the remote repository if all the git history is needed.

For this purpose, replace the <code>android_opteeos.config</code> file <code>TEE_ARCHIVE_PATH</code> by <code>TEE_GIT_PATH</code>. Then execute <code>load_tee</code> again (with <code>-f</code> option to replace previously loaded source).
}}

== Build the TEE ==

After retrieving the OP-TEE sources, build them using:

 {{PC$}} build_tee

This instruction generates an OP-TEE for every available board. To generate an OP-TEE for one board:

 {{PC$}} build_tee --boardb {{HighlightParam|''<BoardId>''}}or
 {{PC$}} build_tee --current

For more information check the instruction definitions:



To get back more details on available options, run:{{PC$}} build_tee -h
Here after, see the result for the version 1.3:<pre>

Usage: build_tee [Options] [Board] [Command]

  This script builds allows building the OP-TEE OS source

Options:
  -h/ / --help: print this message
  -i/ / --install: update prebuilt images
  -v/r <level> / --rpmb=<level>:
      0: disable RPMB (default)
      1: enable RPMB with TESTKEY for anti-rollback only (TAKE CARE: CFG_RPMB_WRITE_KEY is enabled, fusing the TESTKEY on your device)
      2: enable RPMB with TESTKEY for secure storage (TAKE CARE: CFG_RPMB_WRITE_KEY is enabled, fusing the TESTKEY on your device)
  -v / --version: get script version
  --verbose =<level>: enable build verbosity(1 or 2 depending on level of verbosity required)

Board: Optional (default = all)
  -c/--current: build only for current configuration (board and memory)
  or
  -b/--board       0: no verbosity (default)
      1: remove script filtering
      2: remove script filtering and quiet option for the build
  -d <level> / --debug=<level>: TEE debug level
      0: no debug (default)
      1: TEE core and TA log level 2
      2: TEE core and TA log level 3)
  -b <name> / --board=<name>: set board name = eval or discofrom following list = eval (default: all)


Command: Optional, only one instruction is supported command at a time   supportedclean: execute make clean on targeted module</pre>


== Integrate the TEE ==

To integrate the new OP-TEE solution within your distribution, first the prebuilt images have to be updated:

 {{PC$}} build_tee -i

Then build the full distribution

 {{PC$}} make -j

Finally, update the associated partitions for the device. Refer to [[STM32MP1 Distribution Package for Android#Flashing the built image | Flashing the built image]]

== Build Trusted Applications ==

Customize trusted applications can be built as needed. For this purpose, the configuration file<code>android_tabuild.config</code> located in <code>device/stm/{{HighlightParam|''<STM32Series>''}}-tee/source</code> has to be changed.

To build trusted applications, execute:

 {{PC$}} build_ta

This script generates every applications for all available boards. To generate an application for one board only:

 {{PC$}} build_ta --boardb {{HighlightParam|''<BoardId>''}}or
 {{PC$}} build_ta --current

For more information check the instruction definition:


To get back more details on available options, run:{{PC$}} build_ta -h
Here after, see the result for the version 1.1:<pre>

Usage: build_ta [Options] [Board options]

  This script builds allows building the trust applications (TA) source listed in android_tabuild.config file

Options:
  -h/ / --help: print this message
  -i/ / --install: update prebuilt images
  -v/ / --version: get script version
  --verbose =<level>: enable verbosity (1 or 2 depending on level of verbosity required)Board options:
  -c/--current: build only for current configuration (board and memory)
  or
  -b/--board  -b <name> / --board=<name>: set board name = eval or disco from following list = eval (default: all)</pre>


== Integrate Trusted Applications ==

To integrate the new trusted applications into a distribution, first update the prebuilt images:

 {{PC$}} build_ta -i

Then update the file <code>device.mk</code> copying the trusted application in the <code>/vendor/lib/optee_armtz</code> directory.
<pre><syntaxhighlight lang="make">

PRODUCT_COPY_FILES += \
	device/stm/{{HighlightParam|''<STM32Series>''}}-tee/prebuilt/{{HighlightParam|''<BoardId>''}}/ta/{{HighlightParam|''<UUID>''}}<STM32Series>-tee/prebuilt/<BoardId>/ta/<UUID>.ta:$(TARGET_COPY_OUT_VENDOR)/lib/optee_armtz/{{HighlightParam|''<UUID>''}}.ta</pre><UUID>.ta</syntaxhighlight>


Next build the full distribution

 {{PC$}} make -j

Finally, update the associated partitions on the device. Refer to [[How to populate boards for Android]]
<noinclude>

[[Category:How to Android]]
[[Category:Android]]
{{PublicationRequestId | 13274 | 2019-09-12}}</noinclude>
(4 intermediate revisions by the same user not shown)
Line 63: Line 63:
 
This instruction generates an OP-TEE for every available board. To generate an OP-TEE for one board:
 
This instruction generates an OP-TEE for every available board. To generate an OP-TEE for one board:
   
  {{PC$}} build_tee --board {{HighlightParam|''<BoardId>''}}
+
  {{PC$}} build_tee -b {{HighlightParam|''<BoardId>''}}
or
 
{{PC$}} build_tee --current
 
   
For more information check the instruction definitions:
 
   
  +
To get back more details on available options, run:
 
  {{PC$}} build_tee -h
 
  {{PC$}} build_tee -h
   
  +
Here after, see the result for the version 1.3:
 
<pre>
 
<pre>
Usage: build_tee [Options] [Board] [Command]
+
Usage: build_tee [Options] [Command]
   
   This script builds the OP-TEE OS source
+
   This script allows building the OP-TEE OS source
   
 
Options:
 
Options:
   -h/--help: print this message
+
   -h / --help: print this message
   -i/--install: update prebuilt images
+
   -i / --install: update prebuilt images
   -v/--version: get script version
+
  -r <level> / --rpmb=<level>:
   --verbose <level>: enable verbosity (1 or 2 depending on level of verbosity required)
+
      0: disable RPMB (default)
  +
      1: enable RPMB with TESTKEY for anti-rollback only (TAKE CARE: CFG_RPMB_WRITE_KEY is enabled, fusing the TESTKEY on your device)
  +
      2: enable RPMB with TESTKEY for secure storage (TAKE CARE: CFG_RPMB_WRITE_KEY is enabled, fusing the TESTKEY on your device)
  +
   -v / --version: get script version
  +
   --verbose=<level>: enable build verbosity
  +
      0: no verbosity (default)
  +
      1: remove script filtering
  +
      2: remove script filtering and quiet option for the build
  +
  -d <level> / --debug=<level>: TEE debug level
  +
      0: no debug (default)
  +
      1: TEE core and TA log level 2
  +
      2: TEE core and TA log level 3)
  +
  -b <name> / --board=<name>: set board name from following list = eval (default: all)
   
Board: Optional (default = all)
+
Command: Optional, only one command at a time supported
  -c/--current: build only for current configuration (board and memory)
 
  or
 
  -b/--board <name>: set board name = eval or disco
 
 
 
Command: Optional, only one instruction is supported at a time
 
 
   clean: execute make clean on targeted module
 
   clean: execute make clean on targeted module
 
</pre>
 
</pre>
Line 113: Line 119:
 
This script generates every applications for all available boards. To generate an application for one board only:
 
This script generates every applications for all available boards. To generate an application for one board only:
   
  {{PC$}} build_ta --board {{HighlightParam|''<BoardId>''}}
+
  {{PC$}} build_ta -b {{HighlightParam|''<BoardId>''}}
or
 
{{PC$}} build_ta --current
 
 
 
For more information check the instruction definition:
 
   
  +
To get back more details on available options, run:
 
  {{PC$}} build_ta -h
 
  {{PC$}} build_ta -h
   
  +
Here after, see the result for the version 1.1:
 
<pre>
 
<pre>
 
Usage: build_ta [Options] [Board options]
 
Usage: build_ta [Options] [Board options]
   
   This script builds the trust applications (TA) source listed in android_tabuild.config file
+
   This script allows building the trust applications (TA) source listed in android_tabuild.config file
   
 
Options:
 
Options:
   -h/--help: print this message
+
   -h / --help: print this message
   -i/--install: update prebuilt images
+
   -i / --install: update prebuilt images
   -v/--version: get script version
+
   -v / --version: get script version
   --verbose <level>: enable verbosity (1 or 2 depending on level of verbosity required)
+
   --verbose=<level>: enable verbosity (1 or 2 depending on level of verbosity required)
 
+
   -b <name> / --board=<name>: set board name from following list = eval (default: all)
Board options:
 
  -c/--current: build only for current configuration (board and memory)
 
  or
 
   -b/--board <name>: set board name = eval or disco (default: all)
 
 
</pre>
 
</pre>
   
Line 146: Line 146:
 
Then update the file <code>device.mk</code> copying the trusted application in the <code>/vendor/lib/optee_armtz</code> directory.
 
Then update the file <code>device.mk</code> copying the trusted application in the <code>/vendor/lib/optee_armtz</code> directory.
   
<pre>
+
<syntaxhighlight lang="make">
 
PRODUCT_COPY_FILES += \
 
PRODUCT_COPY_FILES += \
device/stm/{{HighlightParam|''<STM32Series>''}}-tee/prebuilt/{{HighlightParam|''<BoardId>''}}/ta/{{HighlightParam|''<UUID>''}}.ta:$(TARGET_COPY_OUT_VENDOR)/lib/optee_armtz/{{HighlightParam|''<UUID>''}}.ta
+
device/stm/<STM32Series>-tee/prebuilt/<BoardId>/ta/<UUID>.ta:$(TARGET_COPY_OUT_VENDOR)/lib/optee_armtz/<UUID>.ta
</pre>
+
</syntaxhighlight>
   
 
Next build the full distribution
 
Next build the full distribution