Skip to content

Commit 1937851

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 1937851

File tree

6 files changed

+173
-0
lines changed

6 files changed

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