Skip to content

Commit f083d11

Browse files
jsuhaas22jsuhaas22
committed
feat: linux: Add docs on OP-TEE Secure Storage
OP-TEE provides secure storage mechanism. Add docs to explain what it is, its uses and how to compile it. Signed-off-by: Suhaas Joshi <[email protected]>
1 parent acfa2f5 commit f083d11

File tree

6 files changed

+172
-0
lines changed

6 files changed

+172
-0
lines changed

‎configs/AM62AX/AM62AX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,7 @@ linux/Foundational_Components/Power_Management/pm_debug
9595

9696
linux/Foundational_Components/System_Security/SELinux
9797
linux/Foundational_Components/System_Security/Auth_boot
98+
linux/Foundational_Components/System_Security/OPTEE_Secure_Storage
9899

99100
linux/Foundational_Components_Kernel_Users_Guide
100101
linux/Foundational_Components_Kernel_LTP-DDT_Validation

‎configs/AM62PX/AM62PX_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ linux/Foundational_Components/Power_Management/pm_debug
100100

101101
linux/Foundational_Components/System_Security/SELinux
102102
linux/Foundational_Components/System_Security/Auth_boot
103+
linux/Foundational_Components/System_Security/OPTEE_Secure_Storage
103104

104105
linux/Foundational_Components_Kernel_Users_Guide
105106
linux/Foundational_Components_Kernel_LTP-DDT_Validation

‎configs/AM62X/AM62X_linux_toc.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ linux/Foundational_Components/Power_Management/pm_debug
9797

9898
linux/Foundational_Components/System_Security/SELinux
9999
linux/Foundational_Components/System_Security/Auth_boot
100+
linux/Foundational_Components/System_Security/OPTEE_Secure_Storage
100101

101102
linux/Foundational_Components_PRU_Subsystem
102103
linux/Foundational_Components/PRU-ICSS-Linux-Drivers

‎source/linux/Foundational_Components/System_Security/OPTEE_Secure_Storage.rst‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
.. _optee_secure_storage:
2+
3+
*********************
4+
OP-TEE Secure Storage
5+
*********************
6+
7+
There is often the need to store sensitive data securely, such that its
8+
confidentiality and integrity are guaranteed. This data includes cryptographic
9+
keys, certificates and other application-specific or general-purpose data.
10+
11+
To guarantee such security, OP-TEE provides 2 Secure Storage mechanisms:
12+
13+
#. REE FS: Data is stored in the normal world's filesystem, as encrypted binary
14+
blobs.
15+
#. RPMB: Data is stored in a special partition of compliant storage devices such
16+
as eMMC and UFS.
17+
18+
REE FS
19+
======
20+
21+
**REE FS** stands for *Rich Execution Environment Filesystem*; that is, Linux's
22+
filesystem on TI SoCs. When the TA needs to store any data in REE FS mode,
23+
OP-TEE first encrypts the data, and then stores it through the TEE Linux driver
24+
using the userspace process "tee_supplicant".
25+
26+
While REE FS guarantees confidentiality of the data (i.e. only the TA that
27+
encrypted it can decrypt it), it does not provide any protection against
28+
denial-of-service attacks (i.e., if Linux root is compromised, the attacker can
29+
delete these blobs). Further, unless RPMB also has been enabled, there's no
30+
protection provided against replay attacks.
31+
32+
In TI SDK, REE FS is enabled by default. RPMB is disabled, therefore no
33+
protection is provided against replay attacks. The encrypted binary blobs are
34+
stored at ``/var/lib/tee/``.
35+
36+
RPMB
37+
====
38+
39+
**RPMB** stands for *Replay Protection Memory Block*. Storage devices such as
40+
the eMMC on TI SoCs contain a special "RPMB partition". This partition uses an
41+
"Authentication Key" to authenticate each write. Further, it maintains a counter
42+
to count the number of write operation, thereby ensuring protection against
43+
replay attacks.
44+
45+
RPMB does not guarantee confidentiality. Data from the RPMB partition can be
46+
read by any process without requiring the Authentication Key. Therefore,
47+
to ensure confidentialty, the application must provide encryption or use RPMB in
48+
conjunction with REE FS.
49+
50+
For more information on compiling OP-TEE with RPMB enabled, refer: :ref:`optee-rpmb-flags`.
51+
52+
.. _optee-client-rpmb:
53+
54+
OP-TEE Client and RPMB Emulation Mode
55+
-------------------------------------
56+
57+
The optee-client repository provides a userspace process called
58+
"tee-supplicant", in ``/usr/sbin/``. This process runs as a systemd service
59+
by-default. All OP-TEE operations on secure storage (regardless of whether they
60+
are REE_FS or RPMB) go through tee-supplicant.
61+
62+
OP-TEE client provides a flag "RPMB_EMU". When set to `1`, tee-supplicant
63+
emulates RPMB instead of using the real RPMB on the eMMC. This is useful for
64+
testing and development activities. This "emulated RPMB" exists only in volatile
65+
memory, so it is reset at each boot.
66+
67+
One use-case for "emulated RPMB" is to test the programming of the
68+
Authentication Key, using ``CFG_RPMB_WRITE_KEY=y`` option. Since this is a one-time
69+
and irreversible operation on the real RPMB, it is safer to test it on the
70+
emulated one (which is reset at every boot).
71+
72+
Therefore, to use real RPMB, re-compile optee-client with RPMB_EMU=0 and copy
73+
the tee-supplicant to ``/usr/sbin/``. For more details, see: :ref:`optee-client-build`.
74+
75+
76+
Programming the Authentication Key
77+
----------------------------------
78+
79+
Initially, on a new TI board, there's no key programmed into the eMMC for the
80+
RPMB.
81+
82+
There are 2 ways to program the key:
83+
84+
#. Use tools like ``mmc-utils`` to write the key.
85+
#. Use the ``CFG_RPMB_WRITE_KEY=y`` flag while compiling OP-TEE.
86+
87+
The recommended approach is to use 3rd party tools like
88+
``mmc-utils``. ``CFG_RPMB_WRITE_KEY=y`` makes OP-TEE send the key to the normal
89+
world in plain-text, therefore it must always be kept disabled in production
90+
builds.
91+
92+
If ``CFG_RPMB_WRITE_KEY=y`` is being used for programming the key in factory,
93+
then 2 sets of OP-TEE binaries are required:
94+
95+
#. the first, with ``CFG_RPMB_WRITE_KEY=y``, to program the key.
96+
#. the second, with ``CFG_RPMB_WRITE_KEY=n``, to be used in production.
97+
98+
.. warning::
99+
100+
If ``CFG_RPMB_WRITE_KEY`` is set to =y, OP-TEE sends the key in plain-text to
101+
Linux normal world. Therefore, ensure that it is **NEVER** enabled in
102+
production builds. To avoid accidents, the recommended way is to **never**
103+
use ``CFG_RPMB_WRITE_KEY=y`` at all, and instead to just rely on third-party
104+
tools like ``mmc-utils``.
105+
106+
.. warning::
107+
108+
The RPMB Authentication Key is one-time programmable only. Once written, it
109+
cannot be re-written or modified. Thus if the wrong key is written, or the
110+
key is lost, the RPMB partition of the device becomes un-usable. Be careful
111+
in writing the key.
112+
113+
If OP-TEE has been compiled with ``CFG_RPMB_WRITE_KEY``, and tee-supplicant has
114+
been compiled with RPMB_EMU=1, then the key will be programmed to the
115+
emulated RPMB, and will be reset at each boot. This is good for testing and
116+
development phase.
117+
118+
However, if RPMB_EMU=0 with ``CFG_RPMB_WRITE_KEY``, or you are using other tools,
119+
then the key is programmed to the real RPMB, therefore be careful!
120+
121+
122+
OP-TEE Secure Storage Example
123+
*****************************
124+
125+
To demonstrate secure storage in OP-TEE, use the
126+
``optee_examples_secure_storage`` binary in the filesystem.
127+
128+
.. code::
129+
130+
optee_examples_secure_storage
131+
132+
This example reads and writes raw data from and to the secure storage. This
133+
secure storage could be either REE_FS or RPMB or both, based on
134+
configuration. By default, it is REE_FS.

‎source/linux/Foundational_Components_OPTEE.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ of entropy can work around these issues.
7575
7676
$ make CROSS_COMPILE="$CROSS_COMPILE_32" CROSS_COMPILE64="$CROSS_COMPILE_64" PLATFORM=k3-|__OPTEE_PLATFORM_FLAVOR__| CFG_ARM64_core=y CFG_WITH_SOFTWARE_PRNG=y
7777
78+
.. _optee-rpmb-flags:
7879

7980
Secure Storage with RPMB (For HS)
8081
*********************************
@@ -84,10 +85,31 @@ KEK embedded in them that is programmed across OP-TEE instances that are distrib
8485
in a derived manner. Each HS device has its own HUK signing key (DKEK) which is different
8586
from other HS devices.
8687

88+
To learn more about secure storage in OP-TEE, refer: :ref:`optee_secure_storage`.
89+
8790
For enabling RPMB support along with secure storage, additional flags need to be passed to
8891
the build instructions. The information for the flags can be found here.
8992
https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
9093

94+
Two flags of interest are:
95+
96+
#. ``CFG_RPMB_FS=y``: Enables RPMB support.
97+
#. ``CFG_RPMB_WRITE_KEY=y``: Enables OP-TEE to write the Authentication Key if a
98+
key is not already programmed.
99+
100+
.. warning::
101+
102+
``CFG_RPMB_WRITE_KEY`` should never be enabled in a production build. It makes
103+
OP-TEE send the Authentication Key in plain-text to normal world, which is a
104+
huge security risk! Keep it disabled in production builds.
105+
106+
.. note::
107+
108+
``CFG_RPMB_WRITE_KEY`` is a convenience feature provided by OP-TEE for easy key
109+
writing. A key can be written even with it disabled. That is, in fact, the
110+
recommended approach to writing a key. To write a key without
111+
``CFG_RPMB_WRITE_KEY``, use third-party tools such as ``mmc-utils``.
112+
91113
There is a hybrid mode in which both the flags i.e `CFG_REE_FS=y` and `CFG_RPMB_FS=y` are enabled.
92114
This mode stores the state of the Secure Storage directory in RPMB partition to check for the
93115
integrity of the data present in it. It is the recommended way.
@@ -107,15 +129,27 @@ E.g. For enabling hybrid mode of RPMB along with REE_FS
107129
OPTEE-client also needs to be updated to enable the use of real
108130
emmc instead of the virtual emmc that is enabled by default
109131

132+
.. _optee-client-build:
133+
110134
Getting OP-TEE Client source code
111135
---------------------------------
112136

137+
To get optee_client source code, do:
138+
139+
.. rubric:: Getting OP-TEE Client source code
140+
113141
.. code-block:: console
114142
115143
$ git clone https://github.com/OP-TEE/optee_client
116144
117145
.. rubric:: Building OP-TEE Client with RPMB support
118146

147+
To use emulated RPMB, set RPMB_EMU=1. Otherwise, set RPMB_EMU=0. For details,
148+
see: :ref:`optee-client-rpmb`.
149+
150+
For example, the following command builds optee_client to use the real RPMB,
151+
instead of the emulated one.
152+
119153
.. code-block:: console
120154
121155
$ make CROSS_COMPILE="$CROSS_COMPILE_64" PLATFORM=k3 CFG_TEE_SUPP_LOG_LEVEL=2 RPMB_EMU=0 CFG_ARM64_core=y

‎source/linux/Foundational_Components_Security.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ Security
1111
Foundational_Components_Secure_Boot
1212
Foundational_Components/System_Security/SELinux
1313
Foundational_Components/System_Security/Auth_boot
14+
Foundational_Components/System_Security/OPTEE_Secure_Storage

0 commit comments

Comments
 (0)