Skip to content

Commit

Permalink
rm: security: update stm32mp1 article
Browse files Browse the repository at this point in the history 
Add details about implicit build-time signing and using provision
script.

Signed-off-by: Igor Opaniuk <[email protected]>
  • Loading branch information
@igoropaniuk
igoropaniuk committed Sep 1, 2023
1 parent b43482f commit 362074b
Showing 1 changed file with 141 additions and 13 deletions.
154 changes: 141 additions & 13 deletions source/reference-manual/security/secure-boot-stm32mp1.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,8 @@ 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.

How to Secure the Platform
--------------------------

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.
Expand Down Expand Up @@ -72,9 +71,131 @@ 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.

To fuse the public key hash, 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::

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

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

Automatic Signing Using Yocto
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The FSBL binary (TF-A BL2) must be signed using a generated key pair.
There are two possible ways to do this: automatic implicit signing during
build time, and manually. In both cases, `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`::

#
# STM32CubeProgrammer STM32MP Signing Tool configuration
#
STM32_ROT_SIGN_ENABLE ??= "1"
STM32_CUBE_PATH ??= "/usr/local/STMicroelectronics/STM32Cube/STM32CubeProgrammer"
STM32_ROT_KEY_PATH ??= "${TOPDIR}/../tools/lmp-tools/security/stm32mp1/"
STM32_ROT_KEY_PATH[vardepsexclude] += "TOPDIR"
STM32_ROT_KEY_PASSWORD ??= "foundries"


* ``STM32_CUBE_PATH`` contains the correct path to STM32Cube installation.
* ``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::

flashlayouts-stm32mp1$ ls -lah
total 558M
drwxr-xr-x 2 user user 4,0K aug 17 12:47 .
drwxr-xr-x 9 user user 12K aug 17 12:48 ..
-rwxr-xr-x 1 user user 28K aug 17 12:47 create_sdcard_from_flashlayout.sh
-rw-r--r-- 1 user user 1,5M aug 17 12:47 fip-stm32mp157c-dk2-optee.bin
-rwxr-xr-x 1 user user 609 aug 17 12:47 FlashLayout_sd_stm32mp157c-dk2-optee.tsv
-rw-r--r-- 1 user user 709M aug 17 12:47 lmp-base-console-image-stm32mp15-disco-sec.ext4
-rw-r--r-- 1 user user 198K aug 17 12:47 tf-a-stm32mp157c-dk2-sdcard_Signed.stm32
-rw-r--r-- 1 user user 198K aug 17 12:47 tf-a-stm32mp157c-dk2-sdcard.stm32
-rw-r--r-- 1 user user 198K aug 17 12:47 tf-a-stm32mp157c-dk2-emmc_Signed.stm32
-rw-r--r-- 1 user user 198K aug 17 12:47 tf-a-stm32mp157c-dk2-emmc.stm32
-rw-r--r-- 1 user user 194K aug 17 12:47 tf-a-stm32mp157c-dk2-uart_Signed.stm32
-rw-r--r-- 1 user user 194K aug 17 12:47 tf-a-stm32mp157c-dk2-uart.stm32
-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::

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``)::

flashlayouts-stm32mp1$ cat FlashLayout_emmc_stm32mp157c-ev1-optee.tsv
#Opt Id Name Type IP Offset Binary
- 0x01 fsbl-boot Binary none 0x0 tf-a-stm32mp157c-ev1-usb_Signed.stm32
- 0x03 fip-boot Binary none 0x0 fip-stm32mp157c-ev1-optee.bin
PD 0x04 fsbl1 Binary mmc1 boot1 combo-emmc-tfa-fip-stm32mp157c-ev1.bin
PD 0x05 fsbl2 Binary mmc1 boot2 combo-emmc-tfa-fip-stm32mp157c-ev1.bin
PED 0x06 u-boot-env Binary mmc1 0x00080000 none
P 0x10 rootfs System mmc1 0x00100000 lmp-base-console-image-stm32mp15-eval.ext4

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::

$ 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 put

Check warning on line 155 in source/reference-manual/security/secure-boot-stm32mp1.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/secure-boot-stm32mp1.rst", "range": {"start": {"line": 155, "column": 4}}}, "severity": "INFO"}
them to `stm32-mfgtool-files` (similar to `flashlayouts-stm32mp1`)
directory before executing `provision.sh` script. For details check
`Sign and Deploy the BL2 Image Manually` section.

Switch to ``root`` user, 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:

.. prompt:: bash #, auto

# cd deploy/images/stm32mp15-eval-sec
# ./stm32-mfgtool-files/provision.sh --pub-key-hash <key_dir>/publicKeyhash.bin
pubkey: dab712cd a4b45564 f70a5706 2135e39c 88e89139 0c20219b 93da5419 c65d1fbd
count: 8
-------------------------------------------------------------------
STM32CubeProgrammer v2.11.0
-------------------------------------------------------------------

....
....
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.

Flash System Images to SD/eMMC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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::

=> mmc rescan
=> STM32MP> fatls mmc 0:4
Expand Down Expand Up @@ -117,10 +238,12 @@ To validate, read back the OTP, using the same ``stm32key`` command::
HASK key is not locked!


Sign and Deploy the BL2 image
-----------------------------
.. _deploy-bl2-manually:

Sign and Deploy the BL2 Image Manually
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The FSBL binary (TF-A BL2) must be signed. `STM32 Signing tool`_ allows to
`STM32 Signing tool`_ allows to
fill the STM32 binary header that is parsed by the embedded software to
authenticate each binary.

Expand Down Expand Up @@ -156,15 +279,20 @@ Validate that signature and sign info (algo etc.) were added to the image::
01 df ae 4c cd 99 12 bc d3 fc 9b 30 7a 77 c5 2b f0 5b 01 f3 2e bb c3 71 db a4 40 93 2c 01 3f a2
Binary type: 0x10

To deploy signed image to the SD card existing non signed images
must be replaced. That can be achieved with a simple ``dd`` command as well

In the case where the WIC image is used for flashing, you have to manually deploy the signed images to the SD card after flashing the WIC image.

Check warning on line 283 in source/reference-manual/security/secure-boot-stm32mp1.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.sentence-length] Aim for sentences no longer than 25 words

Raw Output:
{"message": "[Fio-docs.sentence-length] Aim for sentences no longer than 25 words", "location": {"path": "source/reference-manual/security/secure-boot-stm32mp1.rst", "range": {"start": {"line": 283, "column": 1}}}, "severity": "INFO"}
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)::

$ 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

.. warning::

``dd`` is not needed if the ``FlashLayout`` approach is used.

Booting Signed Images
---------------------
^^^^^^^^^^^^^^^^^^^^^

When a signed binary is used, the BootROM code will authenticate and
start the FSBL, which will report authentication status::
Expand All @@ -180,7 +308,7 @@ not closed, it will be still able to perform image authentication, but 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.
Expand Down

0 comments on commit 362074b

Please sign in to comment.