Skip to content

Commit

Permalink
Cleanup secure-boot stm32mp1 security rm page
Browse files Browse the repository at this point in the history 
Changes made for style, readability, and clarity.

QA steps: ran linter, and viewed rendered output.
No issues found.

This commit applies to FFTK-2795

Signed-off-by: Katrina Prosise <katrina.prosise@foundries.io>
  • Loading branch information
@kprosise
kprosise committed Jan 10, 2024
1 parent 424f2c8 commit b9e75fe
Showing 1 changed file with 55 additions and 74 deletions.
129 changes: 55 additions & 74 deletions source/reference-manual/security/secure-boot-stm32mp1.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,37 +5,34 @@
Secure Boot on STM32MP1
=======================

Secure boot is a key feature to guarantee a secure platform. STM32MP1 boot
sequence supports a trusted boot chain that ensures that the loaded images
are authenticated and checked in integrity before being used.
Secure Boot is a key feature towards having a secure platform.
The STM32MP1 boot sequence supports a trusted boot chain.
This ensures that the loaded images are authenticated and integrity checked before being used.

Our Implementation
------------------

Foundries.io LmP uses U-Boot as the bootloader with TF-A BL2 being its first
stage loader. The secure boot implementation will put the IC in a secure state
accepting only signed TF-A BL2 firmware.
The LmP uses U-Boot as the bootloader, with TF-A BL2 as the first stage loader.
The Secure Boot implementation puts the IC in a secure state, accepting only signed TF-A BL2 firmware.

TF-A then boots the trusted execution environment - OP-TEE - where we run an
'early' trusted application, fiovb - Foundries.io Verified Boot. This trusted
application provides secure access to the Replay Protected Memory Block partition
in eMMC which is used to store keys, firmware and rollback information.
Next, TF-A boots the trusted execution environment—OP-TEE—where we run an 'early' trusted application: fiovb (Foundries.io Verified Boot).
This trusted application provides secure access to the Replay Protected Memory Block partition in eMMC.
This is used to store keys, firmware, and rollback information.

OP-TEE also prepares the next stage bootloader - U-Boot - and generates an
overlay DTS for the Linux kernel consumption. U-boot also implements the fiovb
command to validate the trusted application functionality. U-boot then jumps to
the kernel entry point.
OP-TEE also prepares the next stage bootloader—U-Boot—and generates an overlay DTS for Linux® kernel consumption.
U-boot also implements the fiovb command to validate the trusted application functionality.
U-boot then jumps to the kernel entry point.

Generate RoT ECC key Pair
-------------------------
The first step is to generate the ECC key pair and commit the fuse table
to the hardware. This can be done with the STM32 KeyGen tool, which is part of
the `STM32CubeProgrammer SDK`_ software package.

The first step is generating the ECC key pair and committing the fuse table to the hardware.
This can be done with the STM32 KeyGen tool, part of the `STM32CubeProgrammer SDK`_ software package.

.. note::
For development purposes, we keep sample keys and certificates at `lmp-tools/security/stm32mp1`_.

Here is an example of generating a key pair using KeyGen tool::
Here is an example of generating a key pair using the KeyGen tool::

$ cd STM32CubeProgrammer
STM32CubeProgrammer$ ./bin/STM32MP_KeyGen_CLI
Expand Down Expand Up @@ -67,27 +64,24 @@ Here is an example of generating a key pair using KeyGen tool::
.. note::
The password for ``lmp-tools`` sample keys is ``foundries``.

The tool also generates a third file containing the public key hash (PKH) that
should be fused to OTP and used to authenticate the public key on the
target. For more details refer to ST's `STM32 KeyGen tool`_ guide.
The tool also generates a third file containing the public key hash (PKH) that should be fused to OTP.
This is used to authenticate the public key on the target.
For more details refer to ST's `STM32 KeyGen tool`_ guide.


How to Secure the Platform (Automatic Approach)
-----------------------------------------------

This approach can be used for both STM32MP15 Discovery and Evaluation kits.
This approach can be used for both STM32MP15 Discovery and the Evaluation kits.

Automatic Signing Using LmP
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The FSBL binary (TF-A BL2) must be signed using a key pair generated by
`STM32MP_KeyGen_CLI` tool in the previous section.
There are two possible ways to do this: during the LmP build time, or
manually before deploying binaries to a destination board. In both cases,
`STM32 Signing tool`_ needs to be installed.
The FSBL binary (TF-A BL2) must be signed using a key pair generated by ``STM32MP_KeyGen_CLI``.
There are two possible ways to do this: during LmP build time, or manually, before deploying binaries to a destination board.
In both cases, the `STM32 Signing tool`_ needs to be installed.

To enable implicit automatic signing of boot images during build time
uncomment these lines in your `conf/local.conf`::
To enable implicit, automatic signing of boot images during build time, uncomment the following lines in your `conf/local.conf`::

#
# STM32CubeProgrammer STM32MP Signing Tool configuration
Expand All @@ -103,9 +97,8 @@ uncomment these lines in your `conf/local.conf`::
* ``STM32_ROT_KEY_PATH`` contains the correct path to generated RoT key pair.
* ``STM32_ROT_KEY_PASSWORD`` contains the correct password to RoT private key.

To sign boot images manually using `STM32 Signing tool`_,
sign each ``tf-a-*.stm32`` image in the ``flashlayouts-stm32mp1`` deploy
directory. Place them alongside the unsigned binaries::
To sign boot images manually using the `STM32 Signing tool`_, sign each ``tf-a-*.stm32`` image in the ``flashlayouts-stm32mp1`` deploy directory.
Place them alongside the unsigned binaries::

flashlayouts-stm32mp1$ ls -lah
total 558M
Expand All @@ -124,13 +117,13 @@ directory. Place them alongside the unsigned binaries::
-rw-r--r-- 1 user user 198K aug 17 12:47 tf-a-stm32mp157c-dk2-usb_Signed.stm32
-rw-r--r-- 1 user user 198K aug 17 12:47 tf-a-stm32mp157c-dk2-usb.stm32

Create ``combo*`` images using signed binaries in deploy directory::
Create ``combo*`` images using signed binaries in the deploy directory::

flashlayouts-stm32mp1$ cp tf-a-stm32mp157c-dk2-emmc_Signed.stm32 combo-emmc-tfa-fip-stm32mp157c-ev1.bin
flashlayouts-stm32mp1$ dd if=fip-stm32mp157c-dk2-optee.bin of=combo-emmc-tfa-fip-stm32mp157c-ev1.bin bs=1024 seek=256 conv=notrunc


Adjust FlashLayout file, so it uses signed version (``s/tf-a-stm32mp157c-ev1-usb.stm32/tf-a-stm32mp157c-ev1-usb_Signed.stm32/g``)::
Adjust the FlashLayout file, so it uses the signed version (``s/tf-a-stm32mp157c-ev1-usb.stm32/tf-a-stm32mp157c-ev1-usb_Signed.stm32/g``)::

flashlayouts-stm32mp1$ cat FlashLayout_emmc_stm32mp157c-ev1-optee.tsv
#Opt Id Name Type IP Offset Binary
Expand All @@ -144,28 +137,25 @@ Adjust FlashLayout file, so it uses signed version (``s/tf-a-stm32mp157c-ev1-usb
Provision PKH, HUK and RPMB
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The ``stm32-mfgtool-files`` recipe contains the tools needed for provisioning
PKH/HUK, and programming the RPMB key on the destination device.
To use, build the ``lmp-mfgtool`` distro. For example::
The ``stm32-mfgtool-files`` recipe contains the tools needed for provisioning PKH/HUK, and programming the RPMB key on the destination device.
To use, build the ``lmp-mfgtool`` distro::

$ DISTRO=lmp-mfgtool MACHINE=stm32mp15-eval-sec . setup-environment
$ bitbake stm32-mfgtool-files

.. warning::

If automatic signing is disabled, sign all boot images manually and copy
to `stm32-mfgtool-files` directory before executing `provision.sh` script.
For details check `Sign and Deploy the BL2 Image Manually` section about
similar approach for `flashlayout-stm32mp1`.
If automatic signing is disabled, sign all boot images manually, and copy to the ``stm32-mfgtool-files`` directory before executing ``provision.sh``.
See the :ref:`deploy-bl2-manually` section for a similar approach for ``flashlayout-stm32mp1``.

Switch to ``root`` user, and add the path to STM32Cube to ``PATH``:
Switch to user ``root``, and add the path to STM32Cube to ``PATH``:

.. prompt:: bash $,#, auto

$ sudo -s
# export PATH=$PATH:<path_to_stm32cube>

Execute script, providing path to the PKH binary file:
Execute script, providing the path to the PKH binary file:

.. prompt:: bash #, auto

Expand All @@ -182,9 +172,8 @@ Execute script, providing path to the PKH binary file:
Provision is finished


After execution, the device is provisioned with PKH and HUK
values. The RPMB key (relevant only when eMMC-based board is used) is
programmed as well.
After execution, the device is provisioned with PKH and HUK values.
The RPMB key (relevant only when eMMC-based board is used) is programmed as well.

Flash System Images to SD/eMMC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -194,9 +183,9 @@ How to Secure the Platform (Manual Approach)

Fuse PKH Manually
^^^^^^^^^^^^^^^^^
If you need to fuse the public key hash manually, copy it
to the first FAT partition of your SD boot card. During the boot process, stop
in U-Boot console and run these commands::

If you need to fuse the public key hash manually, copy it to the first FAT partition of your SD boot card.
During the boot process, drop into the U-Boot console and run these commands::

=> mmc rescan
=> STM32MP> fatls mmc 0:4
Expand All @@ -216,10 +205,10 @@ in U-Boot console and run these commands::

.. warning::

Once the fuses have been programmed they can't be modified.
Once the fuses have been programmed, they can not be modified.

Verify that ``stm32key`` command has printed valid key hashes, and if
everything is correct fuse these values to OTP::
Verify that ``stm32key`` has printed valid key hashes.
If everything is correct, fuse these values to OTP::

=> stm32key fuse 0xc0000000

Expand All @@ -244,9 +233,7 @@ To validate, read back the OTP, using the same ``stm32key`` command::
Sign and Deploy the BL2 Image Manually
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

`STM32 Signing tool`_ allows to
fill the STM32 binary header that is parsed by the embedded software to
authenticate each binary.
`STM32 Signing tool`_ allows you to fill the STM32 binary header that is parsed by the embedded software to authenticate each binary.

To sign the image run::

Expand All @@ -262,7 +249,7 @@ To sign the image run::
Signature verification: SUCCESS
The Signed image file generated successfully: /build-lmp/deploy/images/stm32mp15-disco/arm-trusted-firmware/tf-a-stm32mp157c-dk2-sdcard_Signed.stm32

Validate that signature and sign info (algo etc.) were added to the image::
Validate that signature and sign info (algo etc) were added to the image::

STM32CubeProgrammer$ ./bin/STM32MP_SigningTool_CLI -dump /build-lmp/deploy/images/stm32mp15-disco/arm-trusted-firmware/tf-a-stm32mp157c-dk2-sdcard_Signed.stm32
Magic: 0x53544d32
Expand All @@ -281,9 +268,9 @@ Validate that signature and sign info (algo etc.) were added to the image::
Binary type: 0x10


When WIC image is used for flashing, deploy the signed images to the SD card after flashing the WIC image.
Here the existing non signed images must be replaced. This can be achieved with a simple ``dd`` command as well
(instead of mmcblkx specify correct device)::
When a WIC image is used for flashing, deploy the signed images to the SD card after flashing the WIC image.
Here the existing unsigned images must be replaced.
This can be achieved with a ``dd`` command as well (instead of mmcblkx specify correct device)::

$ sudo dd if=/build-lmp/deploy/images/stm32mp15-disco/arm-trusted-firmware/tf-a-stm32mp157c-dk2-sdcard_Signed.stm32 bs=1024 seek=17 of=/dev/mmcblkx
$ sudo dd if=/build-lmp/deploy/images/stm32mp15-disco/arm-trusted-firmware/tf-a-stm32mp157c-dk2-sdcard_Signed.stm32 bs=1024 seek=273 of=/dev/mmcblkx
Expand All @@ -295,39 +282,33 @@ Here the existing non signed images must be replaced. This can be achieved with
Booting Signed Images
^^^^^^^^^^^^^^^^^^^^^

When a signed binary is used, the BootROM code will authenticate and
start the FSBL, which will report authentication status::
When a signed binary is used, the BootROM code will authenticate and start the FSBL, which will report authentication status::

NOTICE: CPU: STM32MP157CAC Rev.B
NOTICE: Model: STMicroelectronics STM32MP157C-DK2 Discovery Board
NOTICE: Board: MB1272 Var2.0 Rev.C-01
NOTICE: Bootrom authentication succeeded <------- auth confirmation

A `Bootrom authentication succeeded` message means that BootROM managed
to authenticate the FSBL image and the device can be closed. If the device is
not closed, it will be still able to perform image authentication, but will
boot the image regardless of the result of that authentication.
A ``Bootrom authentication succeeded`` message means that BootROM managed to authenticate the FSBL image and the device can be closed.
If the device is not closed, it will be still able to perform image authentication.
However,it will boot the image regardless of the result of that authentication.

Closing the Device
^^^^^^^^^^^^^^^^^^

As soon as the authentication process is confirmed, the device can be closed
and the user must use signed images.
As soon as the authentication process is confirmed, the device can be closed and the user must use signed images.

OTP ``WORD0`` bit 6 is the OTP bit that closes the device. Fusing this bit
will lock authentication processing and force authentication from the BootROM.
Non signed binaries will not be supported anymore on the target.
OTP ``WORD0`` bit 6 is the OTP bit that closes the device.
Fusing this bit will lock authentication processing, and force authentication from the BootROM.
Unsigned binaries will no longer be supported on the target.

To close the device by fusing OTP WORD0 bit 6 run `stm32key` cmd in U-Boot::
To close the device by fusing OTP WORD0 bit 6, run the `stm32key` cmd in U-Boot::

=> stm32key close

.. seealso::
* :ref:`ref-boot-software-updates-stm32mp1`

.. _STM32MPU Security overview:
https://wiki.st.com/stm32mpu/wiki/Security_overview

.. _STM32 KeyGen tool:
https://wiki.st.com/stm32mpu/wiki/KeyGen_tool

Expand Down

0 comments on commit b9e75fe

Please sign in to comment.