.. include:: /keyword.rst
========
Security
========
Security is an important feature of the MediaTek IoT platform. |IOT-YOCTO| provides a consistent interface for secure development. The following sections describe the security features provided by |IOT-YOCTO| and how to enable security features.
.. contents:: Sections
:local:
:depth: 1
.. _feature-efuse-custom-data:
eFuse Based Custom Data
=======================
|IOT-YOCTO| provides a set of eFuses structured for the persistent data storage. It is composed of 32 bits each Custom Data (C_DATA) in eFuse fields. The number of C_DATA supported and eFuse index are different on different platforms.
- |G350-EVK| supports 6 sets of C_DATA in eFuse fields.
- |G510-G700-EVK| supports 8 sets of C_DATA in eFuse fields.
- |G1200-EVK| supports 8 sets of C_DATA in eFuse fields.
Please check the eFuse index before writing the C_DATA in eFuse fields.
.. caution::
Writing the eFuse fields is an irreversible operation. Please do not program eFuse fields unless you are sure of what you are doing.
.. note::
The eFuse index information is only provided with **NDA license**. Please contact your MediaTek customer window to have access permission for eFuse index information.
Please visit the `MediaTek On-Line `_ and find the *eFuse Writer Development Guide* of the platform by the keyword *IoT_Yocto_eFuse_Writer_Development_Guide*.
.. _feature-anti-rollback:
Anti-Rollback
=============
|IOT-YOCTO| supports a bootloader rollback protection mechanism. When the device is turned on, it will check if the bootloader image loaded has a valid rollback index. To enable |IOT-YOCTO| bootloader rollback protection mechanism, the `patch `_ located in files folder is required and the following U-Boot configuration should be enabled.
.. code:: text
CONFIG_OPTEE=y
CONFIG_MEDIATEK_IOT_AB_BOOT_SUPPORT=y
CONFIG_MEDIATEK_IOT_ROLLBACK_INDEX0=0x00000000
The ``CONFIG_MEDIATEK_IOT_ROLLBACK_INDEX0`` means the rollback index of the bootloader image. The rollback information is usually authorized based on the Chain of Trust (CoT). Even if the user flashes successfully, this mechanism will refuse to boot up when detecting the current bootloader rollback index is lower than the valid rollback index stored. To ensure that a device can not load any old bootloader, it needs to keep a record of the valid rollback index. The implementation of |IOT-YOCTO| Anti-Rollback depends on eFuse fields to store the valid rollback index.
.. note::
Users can use appropriate eFuse fields for the platform index based on the customer application. Please refer to :ref:`Program Rollback Index in eFuse ` section for details.
.. _program-rollback-index-in-efuse:
Program Rollback Index in eFuse
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
According to different platforms, please follow the description to program eFuse fields.
- |G350-EVK| supports 8 sets of BACK_UP in eFuse fields and a total of 32 bits for rollback index purpose.
- |G510-G700-EVK| and |G1200-EVK| can use Custom Data (C_DATA) in eFuse fields for rollback index purpose.
Users can write Custom Data (|G510-G700-EVK|, |G1200-EVK|) and BACK_UP (|G350-EVK|) for valid rollback index in eFuse fields with using eFuse Writer. This is a user-space tool used to read and write eFuse fields.
.. important::
Before programming the **C_DATA** in eFuse fields for rollback index purpose, the user should also enable **C_DATA0_HW_ECC_DIS** in eFuse fields to ensure bit by bit writing capability.
If the current bootloader rollback index ``CONFIG_MEDIATEK_IOT_ROLLBACK_INDEX0`` is lower than the valid rollback index stored, BL33 will detect it and rollback to another ``boot_slot``. It will rise this kind of errors and reset system:
.. code-block::
Invalid rollback index, found 00000000
Rollback.
resetting ...
.. note::
The eFuse index information is only provided with **NDA license**. Please contact your MediaTek customer window to have access permission for eFuse index information.
Please visit the `MediaTek On-Line `_ and find the *eFuse Writer Development Guide* of the platform by the keyword *IoT_Yocto_eFuse_Writer_Development_Guide*.
.. _feature-rpmb-api:
OP-TEE Based Secure Storage
===========================
|IOT-YOCTO| provides a consistent interface for secure storage implementations in OP-TEE. Secure Storage for Replay Protected Memory Block (RPMB) of eMMC devices in OP-TEE is implemented according to what has been defined in TEE Internal Core API.
To enable RPMB in OP-TEE, add the following variables to your ``local.conf``:
.. code-block::
MACHINE_FEATURES:append = " optee-rpmb"
The RPMB partition of eMMC devices cannot be accessed until the security key has been programmed on devices and this is an irreversible action. |IOT-YOCTO| supports generating unique security keys for each device to access the RPMB partition of eMMC devices.
To program |IOT-YOCTO| unique security key, add the following variables to your ``local.conf``:
.. code-block::
MACHINE_FEATURES:append = " optee-rpmb-write"
.. important::
When users add MACHINE_FEATURES with ``optee-rpmb-write``, every attempt to initialize the RPMB in OP-TEE will program the security key on the device automatically, if it has not been programmed.
This security key generated by |IOT-YOCTO| platform is incompatible with other MediaTek platforms.
|IOT-YOCTO| provides a demo tool to access RPMB in OP-TEE for secure storage development. Users can read and write Secure Storage in OP-TEE using ``optee-otp``. To package the ``optee-otp`` tool, add the following variables to your ``local.conf``:
.. code-block::
IMAGE_INSTALL:append = " optee-otp"
- Provide the example that can read an object named ``demo`` for RPMB:
.. prompt:: bash # auto
# optee_otp get demo
- Provide the example that can write an object named ``demo`` for RPMB:
.. prompt:: bash # auto
# optee_otp set demo 0000000011111111
.. important::
When you execute the ``optee-otp`` tool, it also automatically programs the security key on the device if it has not been programmed.
|IOT-YOCTO| retains the secure storage default implementation in OP-TEE. If you use secure storage in OP-TEE and then re-download the rootfs partition, it will cause the TEE file to be wiped. In this case, you may consider compiling with ``CFG_RPMB_FS=y`` and ``CFG_REE_FS=n`` for secure storage in OP-TEE.
For more information about secure storage in OP-TEE, please refer to `OP-TEE documentation `_ and the TEE Core API specification.
FAQ
===
Secure RAM concerning on Secure Boot Flow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1. Does MediaTek AIoT SoC have a Secure RAM?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes, MediaTek AIoT SOC uses EMI memory protection unit(MPU) hardware to protect secure DRAM.
2. If answer of Q1 is yes, does it have access from Normal World after booting?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
No, the secure DRAM regions do not permit to be accessed by Normal World after booting. MT8365 has the EMI MPU settings in TF-A bl31_platform_setup() to make BL31 & BL32 can only be accessed by Secure World.
Besides, BL2 is no longer existed after booting to BL31. https://gitlab.com/mediatek/aiot/bsp/trusted-firmware-a/-/blob/mtk-v2.6/plat/mediatek/mt8365/include/plat_emi_mpu.h#L42
3. Does the secure DRAM exist independently as hardware?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
No, Secure DRAM is supported by MPU HW in EMI controller, and the MPU HW checks the permission on the memory bus connected to external DRAM.
4. How many memory size does your secure DRAM?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It depends on the DRAM size, and users can configure the secure DRAM region with start address and size on demand.
5. Is "EMI memory protection unit(MPU) hardware" the same as TZASC(TrustZone Address Space Controller) ? Or, is it your original hardware?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The EMI MPU hardware design is based on the TZASC mechanism and implemented in EMI controller by MediaTek.
6. Is TrustZone essential requisite for SoC support secure boot feature?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Yes. ARM TrustZone support is necessary for the secure boot mechanism. The system execution state can be separated to normal world and secure world by TrustZone. The verification of secure boot is started and processed in secure world.
By the way, TEE OS(BL32) is optional, the secure boot mechanism can be supported without TEE OS.