diff --git a/source/reference-manual/security/secure-boot-stm32mp1.rst b/source/reference-manual/security/secure-boot-stm32mp1.rst index 3cb1aaf8c..a163a50e4 100644 --- a/source/reference-manual/security/secure-boot-stm32mp1.rst +++ b/source/reference-manual/security/secure-boot-stm32mp1.rst @@ -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. @@ -72,9 +71,132 @@ 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 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. + +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 in 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``):: + + 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 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`. + +Switch to ``root`` user, and add the path to STM32Cube to ``PATH``: + +.. prompt:: bash $,#, auto + + $ sudo -s + # export PATH=$PATH: + +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 /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 @@ -117,10 +239,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. @@ -156,15 +280,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 + +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):: $ 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:: @@ -180,7 +309,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.