Skip to content

feat: linux: Add docs on OP-TEE Secure Storage #539

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cshilwant merged 1 commit into from
Dec 9, 2025
Merged

feat: linux: Add docs on OP-TEE Secure Storage #539

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 75 additions & 20 deletions source/linux/Foundational_Components_OPTEE.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,46 +77,89 @@

.. _secure-storage-with-rpmb:

Secure Storage with RPMB (For HS)
*********************************
OP-TEE Secure Storage

Check warning on line 80 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'OP-TEE Secure Storage'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'OP-TEE Secure Storage'.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 80, "column": 1}}}, "severity": "INFO"}
*********************

OP-TEE provides secure storage functionality. TI SoCs with HS configuration have a
KEK embedded in them that is programmed across OP-TEE instances that are distributed
in a derived manner. Each HS device has its own HUK signing key (DKEK) which is different
from other HS devices.
OP-TEE provides secure storage functionality through two mechanisms:
**REE FS** (Rich Execution Environment Filesystem) and **RPMB**

Check warning on line 84 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'RPMB') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'RPMB') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 84, "column": 58}}}, "severity": "INFO"}

Check warning on line 84 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'REE') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'REE') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 84, "column": 3}}}, "severity": "INFO"}
(Replay Protected Memory Block).

For enabling RPMB support along with secure storage, additional flags need to be passed to
the build instructions. The information for the flags can be found here.
https://optee.readthedocs.io/en/latest/architecture/secure_storage.html
TI SDK enables REE FS by-default, and configures OP-TEE to store

Check warning on line 87 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'REE') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'REE') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 87, "column": 16}}}, "severity": "INFO"}
encrypted binary blobs created by REE FS in

Check warning on line 88 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'REE') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'REE') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 88, "column": 35}}}, "severity": "INFO"}
:file:`/var/lib/tee/`.

There is a hybrid mode in which both the flags i.e `CFG_REE_FS=y` and `CFG_RPMB_FS=y` are enabled.
This mode stores the state of the Secure Storage directory in RPMB partition to check for the
integrity of the data present in it. It is the recommended way.
.. ifconfig:: CONFIG_part_variant in ('AM62LX')

E.g. For enabling hybrid mode of RPMB along with REE_FS
.. note::

.. ifconfig:: CONFIG_part_variant in ('J721S2')
Presently, AM62L does not support RPMB. This support will be added
in subsequent releases. It does support REE FS.

.. code-block:: console
The remaining devices support both: REE FS by-default and RPMB if
OP-TEE binaries are re-compiled with required flags.

$ export CFG_CONSOLE_UART=0x8
For learning more about secure storage in OP-TEE, refer:
https://optee.readthedocs.io/en/latest/architecture/secure_storage.html

.. parsed-literal::
.. ifconfig:: CONFIG_part_variant not in ('AM62LX')

RPMB works in TI SoCs with HS configuration. These embed a KEK
that programs across OP-TEE instances in a derived manner. Each HS
device has its own HUK signing key (DKEK), which is different from
other HS devices. TI SDK disables RPMB by-default. To enable it,
re-compiling OP-TEE with ``CFG_RPMB_FS=y`` flag.

For learning more about secure storage in OP-TEE, and instructions to
enable RPMB, refer:
https://optee.readthedocs.io/en/latest/architecture/secure_storage.html

There is a hybrid mode in which both the flags i.e `CFG_REE_FS=y` and `CFG_RPMB_FS=y` are enabled.
This mode stores the state of the Secure Storage directory in RPMB partition to check for the
integrity of the data present in it. It is the recommended way.

E.g. For enabling hybrid mode of RPMB along with REE_FS

.. ifconfig:: CONFIG_part_variant in ('J721S2')

.. code-block:: console

$ export CFG_CONSOLE_UART=0x8

.. parsed-literal::

$ make CROSS_COMPILE64="$CROSS_COMPILE_64" PLATFORM=|__OPTEE_PLATFORM_FLAVOR__| CFG_ARM64_core=y CFG_REE_FS=y CFG_RPMB_FS=y

OPTEE-client also needs to be updated to enable the use of real
emmc instead of the virtual emmc that is enabled by default

$ make CROSS_COMPILE64="$CROSS_COMPILE_64" PLATFORM=|__OPTEE_PLATFORM_FLAVOR__| CFG_ARM64_core=y CFG_REE_FS=y CFG_RPMB_FS=y
As an example to show the usage of secure storage, the filesystem
provides a binary :file:`/usr/bin/optee_examples_secure_storage`.

OPTEE-client also needs to be updated to enable the use of real
emmc instead of the virtual emmc that is enabled by default
.. code::

optee_examples_secure_storage

For more details, see optee_examples:

Check warning on line 142 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'optee_examples'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'optee_examples'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 142, "column": 23}}}, "severity": "WARNING"}
https://github.com/linaro-swg/optee_examples

Getting OP-TEE Client source code
---------------------------------

To get optee_client source code, do:

Check warning on line 148 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'optee_client'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'optee_client'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 148, "column": 8}}}, "severity": "WARNING"}

.. rubric:: Getting OP-TEE Client source code

.. code-block:: console

$ git clone https://github.com/OP-TEE/optee_client

.. rubric:: Building OP-TEE Client with RPMB support

To use emulated RPMB, set RPMB_EMU=1. Otherwise, set RPMB_EMU=0.

Check warning on line 158 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'RPMB') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'RPMB') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 158, "column": 17}}}, "severity": "INFO"}

For example, the following command builds optee_client to use the real RPMB,

Check warning on line 160 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'RPMB') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'RPMB') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 160, "column": 72}}}, "severity": "INFO"}

Check warning on line 160 in source/linux/Foundational_Components_OPTEE.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'optee_client'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'optee_client'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/Foundational_Components_OPTEE.rst", "range": {"start": {"line": 160, "column": 43}}}, "severity": "WARNING"}
instead of the emulated one.

.. code-block:: console

$ make CROSS_COMPILE="$CROSS_COMPILE_64" PLATFORM=k3 CFG_TEE_SUPP_LOG_LEVEL=2 RPMB_EMU=0 CFG_ARM64_core=y
Expand Down Expand Up @@ -146,3 +189,15 @@
.. note::

tee-pager_v2.bin may be called bl32.bin in other documentation.

|

.. ifconfig:: CONFIG_part_variant not in ('AM62LX')

.. rubric:: PKCS#11

PKCS#11 is a cryptographic token interface standard that allows applications
to access cryptographic services through a platform-independent API.

For userland integration details, refer:
https://optee.readthedocs.io/en/latest/building/userland_integration.html
Loading