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 <igor.opaniuk@foundries.io>
  • Loading branch information
@igoropaniuk
igoropaniuk committed Aug 23, 2023
1 parent b43482f commit 4093551
Showing 1 changed file with 117 additions and 13 deletions.
130 changes: 117 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

Check failure on line 29 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.Header-cap] 'Generate RoT ECC key pair': Use APA title case: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case

Raw Output:
{"message": "[Fio-docs.Header-cap] 'Generate RoT ECC key pair': Use APA title case: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case", "location": {"path": "source/reference-manual/security/secure-boot-stm32mp1.rst", "range": {"start": {"line": 29, "column": 1}}}, "severity": "ERROR"}
-------------------------
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,109 @@ 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 that: automatic implicit signing during
build time and manual one. In both cases `STM32 Signing tool`_ is needed 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.

In case you still want to sign boot images manually using `STM32 Signing tool`_,

Check warning on line 105 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": 105, "column": 1}}}, "severity": "INFO"}
please sign each `tf-a-*.stm32` image in the `flashlayouts-stm32mp1` deploy
directory and put all these image along with 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 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


Provision PKH, HUK and RPMB
^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

Check failure on line 130 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.Branding-and-names] Use 'LmP' instead of 'lmp'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'LmP' instead of 'lmp'", "location": {"path": "source/reference-manual/security/secure-boot-stm32mp1.rst", "range": {"start": {"line": 130, "column": 28}}}, "severity": "ERROR"}

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

.. warning::

If automatic signing is disabled, you need to sign all boot images manually

Check warning on line 137 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": 137, "column": 4}}}, "severity": "INFO"}
and put signed binaries 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 your PATH env variable::

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

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

# 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 of this script device will be provisioned with PKH and HUK

Check warning on line 162 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": 162, "column": 1}}}, "severity": "INFO"}
values, also RPMB key (relevant only when eMMC-based board is used) is
programmed.

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

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

Fuse PKH Manually
^^^^^^^^^^^^^^^^^
If for some reason 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 +216,10 @@ To validate, read back the OTP, using the same ``stm32key`` command::
HASK key is not locked!


Sign and Deploy the BL2 image
-----------------------------
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 +255,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 case WIC image is used for flashing, you have to deploy manually all signed images to the SD card after flashing WIC image

Check warning on line 259 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": 259, "column": 1}}}, "severity": "INFO"}
to SD, where existing non signed images must be replaced. That 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` step is not needed if `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 +284,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 4093551

Please sign in to comment.