1########### 2Secure boot 3########### 4 5.. toctree:: 6 :maxdepth: 1 7 8 BL1 Immutable bootloader <bl1.rst> 9 Rollback Protection <secure_boot_rollback_protection.rst> 10 HW Key integration <secure_boot_hw_key_integration.rst> 11 12For secure devices it is security critical to enforce firmware authenticity to 13protect against execution of malicious software. This is implemented by building 14a trust chain where each step in the execution chain authenticates the next 15step before execution. The chain of trust is based on a "Root of Trust" which 16is implemented using asymmetric cryptography. The Root of Trust is a combination 17of an immutable bootloader and a public key (ROTPK). 18 19.. Warning:: 20 In order to implement a proper chain of trust functionality, it is 21 mandatory that the first stage bootloader and ROTPK is stored in an 22 **immutable** way. To achieve this the bootloader code must be stored and 23 executed from ROM or such part of flash memory which supports write 24 protection. ROTPK can be stored in a one-time-programmable (OTP) memory. If 25 the SoC has a built-in BL1 (immutable) bootloader and the immutability of 26 TF-M secure boot code is not guaranteed then TF-M secure boot code must be 27 authenticated by BL1 bootloader before execution. If immutability of root 28 of trust (first stage bootloader + ROTPK) is not ensured then there is a 29 risk that the secure boot process could be bypassed, which could lead to 30 arbitrary code execution on the device. Current TF-M secure boot code is 31 intended to be a second stage bootloader, therefore it requires 32 authentication before execution. If TF-M secure boot code is used as a first 33 stage bootloader then it must be stored according to the above requirements. 34 35******************************* 36Second stage bootloader in TF-M 37******************************* 38By default, the MCUboot project from 39`GitHub <https://github.com/mcu-tools/mcuboot>`__ is used as the secure 40bootloader in TF-M. The repository is going to be automatically downloaded by 41CMake. The version downloaded can be controlled by the ``MCUBOOT_VERSION`` 42CMake variable. If you wish to use a locally downloaded copy, the CMake variable 43``MCUBOOT_PATH`` can be set to its location. This document contains information 44about how MCUboot has been integrated to TF-M. For further information about 45MCUboot design please refer to the `MCUBoot homepage <https://www.mcuboot.com/>`__. 46 47Bootloader is started when CPU is released from reset. It runs in secure mode. 48It authenticates the firmware image by hash (SHA-256) and digital signature 49(RSA-3072) validation. Public key, that the checks happens against, can be built 50into the bootloader image or can be provisioned to the SoC during manufacturing. 51Metadata of the image is delivered together with the image itself in a header 52and trailer section. In case of successful authentication, bootloader passes 53execution to the secure image. Execution never returns to bootloader until 54next reset. 55 56A default RSA key pair is stored in the repository, public key is in ``keys.c`` 57and private key is in ``root-RSA-3072.pem``. 58 59.. Danger:: 60 DO NOT use the default keys in a production code, they are exclusively 61 for testing! 62 63The private key must be stored in a safe place outside of the repository. 64``imgtool.py`` (found in the ``scripts`` directory in the MCUBoot repository, 65or installed through the pip package manager) can be used to generate new key 66pairs. 67 68The bootloader can handle the secure and non-secure images independently 69(multiple image boot) or together (single image boot). In case of multiple image 70boot they are signed independently with different keys and they can be updated 71separately. In case of single image boot the secure and non-secure image is 72handled as a single blob, therefore they must be contiguous in the device 73memory. In this case they are signed together and also they can be updated only 74together. In order to have the same artefacts at the end of the build regardless 75of how the images are handled (independently or together) the images are always 76concatenated. In case of single image boot they are concatenated first and then 77signed. In case of multiple image boot they are separately signed first and then 78concatenated. Preparation of payload is done by Python scripts: 79``bl2/ext/mcuboot/scripts/``. At the end of a successful build the signed TF-M 80payload can be found in: ``<build_dir>/bin/tfm_s_ns_signed.bin`` 81 82********************* 83Integration with TF-M 84********************* 85MCUBoot assumes a predefined memory layout which is described below (applicable 86for AN521). It is mandatory to define the primary slot and the secondary slot 87partitions, but their size and location can be changed:: 88 89 - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot 90 - 0x0008_0000 - 0x000F_FFFF: Primary slot : Single binary blob: 91 Secure + Non-Secure image; 92 Primary memory partition 93 - 0x0008_0000 - 0x0008_03FF: Common image header 94 - 0x0008_0400 - 0x0008_xxxx: Secure image 95 - 0x0008_xxxx - 0x0010_03FF: Padding (with 0xFF) 96 - 0x0010_0400 - 0x0010_xxxx: Non-secure image 97 - 0x0010_xxxx - 0x0010_xxxx: Hash value(SHA256), RSA signature and other 98 metadata of combined image 99 100 - 0x0018_0000 - 0x0027_FFFF: Secondary slot : Secure + Non-Secure image; 101 Secondary memory partition, structured 102 identically to the primary slot 103 - 0x0028_0000 - 0x0037_FFFF: Scratch area, only used during image 104 swapping 105 106Multiple image boot requires a slightly different layout:: 107 108 - 0x0000_0000 - 0x0007_FFFF: BL2 bootloader - MCUBoot 109 - 0x0008_0000 - 0x000F_FFFF: Primary slot : Secure image 110 - 0x0008_0000 - 0x0008_03FF: Secure image header 111 - 0x0008_0400 - 0x000x_xxxx: Secure image 112 - 0x000x_xxxx - 0x000x_xxxx: Hash value(SHA256), RSA signature and other 113 metadata of secure image 114 115 - 0x0010_0000 - 0x0017_FFFF: Primary slot : Non-secure image 116 - 0x0010_0000 - 0x0010_03FF: Non-secure image header 117 - 0x0010_0400 - 0x001x_xxxx: Non-secure image 118 - 0x001x_xxxx - 0x001x_xxxx: Hash value(SHA256), RSA signature and other 119 metadata of non-secure image 120 121 - 0x0018_0000 - 0x001F_FFFF: Secondary slot : Secure image 122 - 0x0020_0000 - 0x0027_FFFF: Secondary slot : Non-secure image 123 124 - 0x0028_0000 - 0x002F_FFFF: Scratch area, only used during image 125 swapping, used for secure and non-secure 126 image as well 127 128************************** 129Firmware upgrade operation 130************************** 131MCUBoot handles only the firmware authenticity check after start-up and the 132firmware switch part of the firmware update process. Downloading the new version 133of the firmware is out-of-scope for MCUBoot. MCUBoot supports three different 134ways to switch to the new firmware and it is assumed that firmware images are 135executed-in-place (XIP). The default behaviour is the overwrite-based image 136upgrade. In this case the active firmware is always executed from the primary 137slot and the secondary slot is a staging area for new images. Before executing 138the new firmware image, the content of the primary slot must be overwritten with 139the content of the secondary slot (the new firmware image). The second option is 140the image swapping strategy when the content of the two memory slots must be 141physically swapped. This needs the scratch area to be defined in the memory 142layout. The third option is the direct execute-in-place version, which 143eliminates the complexity of image swapping and its administration. Active image 144can be executed from either memory slot, but new firmware must be linked to the 145address space of the proper (currently inactive) memory slot. 146 147Overwrite operation 148=================== 149Active image is stored in the primary slot, and this image is started always by 150the bootloader. Therefore images must be linked to the primary slot. If the 151bootloader finds a valid image in the secondary slot, which is marked for 152upgrade, then the content of the primary slot will be simply overwritten with 153the content of the secondary slot, before starting the new image from the 154primary slot. After the content of the primary slot has been successfully 155overwritten, the header and trailer of the new image in the secondary slot is 156erased to prevent the triggering of another unnecessary image upgrade after a 157restart. The overwrite operation is fail-safe and resistant to power-cut 158failures. For more details please refer to the MCUBoot 159`documentation <https://docs.mcuboot.com/>`__. 160 161Swapping operation 162================== 163This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time 164switch (see `Build time configuration`_). With swapping image upgrade strategy 165the active image is also stored in the primary slot and it will always be 166started by the bootloader. If the bootloader finds a valid image in the 167secondary slot, which is marked for upgrade, then contents of the primary slot 168and the secondary slot will be swapped, before starting the new image from the 169primary slot. Scratch area is used as a temporary storage place during image 170swapping. Update mark from the secondary slot is removed when the swapping is 171successful. The boot loader can revert the swapping as a fall-back mechanism to 172recover the previous working firmware version after a faulty update. The swap 173operation is fail-safe and resistant to power-cut failures. For more details 174please refer to the MCUBoot 175`documentation <https://docs.mcuboot.com/>`__. 176 177.. Note:: 178 179 After a successful image upgrade, user can mark the image as "OK" 180 at runtime by explicitly calling ``psa_fwu_accept``. When this happens, 181 the swap is made "permanent" and MCUBoot will then still choose to run it 182 during the next boot. 183 184 TF-M does not set the image_ok flag, because it is user's duty to determine 185 whether the image is acceptable. Therefore the bootloader will always 186 perform a "revert" (swap the images back) during the next boot. 187 188Direct execute-in-place operation 189================================= 190This operation can be set with the ``MCUBOOT_UPGRADE_STRATEGY`` compile time 191switch (see `Build time configuration`_). When enabling direct-xip operation 192then the active image flag is moved between slots during firmware upgrade. If 193firmware is executed-in-place (XIP), then two firmware images must be generated. 194One of them is linked to be executed from the primary slot memory region and the 195other from the secondary slot. The firmware upgrade client, which downloads the 196new image, must be aware, which slot hosts the active firmware and which acts as 197a staging area and it is responsible for downloading the proper firmware image. 198At boot time MCUBoot inspects the version number in the image header and passes 199execution to the newer firmware version. New image must be marked for upgrade 200which is automatically done by Python scripts at compile time. Image 201verification is done the same way in all operational modes. If new image fails 202during authentication then MCUBoot erases the memory slot and starts the other 203image, after successful authentication. 204 205To select which slot the image is to be executed from, set 206``MCUBOOT_EXECUTION_SLOT`` to the desired index. It is suggested that you create 207two build directories when building images using this mode, as intermediate 208dependencies cannot be reused due to changes in the flash layout. 209 210.. Note:: 211 212 Only single image boot is supported with direct-xip upgrade mode. 213 214RAM Loading firmware upgrade 215============================ 216Musca-S supports an image upgrade mode that is separate to the other (overwrite, 217swapping and dirext-xip) modes. This is the ``RAM load`` mode (please refer 218to the table below). Like the direct-xip mode, this selects the newest image 219by reading the image version numbers in the image headers, but instead of 220executing it in place, the newest image is copied to RAM for execution. The load 221address, the location in RAM where the image is copied to, is stored in the 222image header. 223 224Summary of different modes for image upgrade 225============================================ 226Different implementations of the image upgrade operation (whether through 227overwriting, swapping, direct-xip or loading into RAM and executing from 228there) are supported by the platforms. The table below shows which of these 229modes are supported by which platforms: 230 231+---------------------+-----------------+----------------------------------------------------------+ 232| | Without BL2 [1]_| With BL2 [2]_ | 233+=====================+=================+===============+==========+================+==============+ 234| | XIP | XIP | XIP | XIP | Not XIP | 235+---------------------+-----------------+---------------+----------+----------------+--------------+ 236| | | Overwrite [3]_| Swap [4]_| direct-xip [5]_| RAM load [6]_| 237+---------------------+-----------------+---------------+----------+----------------+--------------+ 238| AN521 | Yes | Yes | Yes | Yes | No | 239+---------------------+-----------------+---------------+----------+----------------+--------------+ 240| AN519 | Yes | Yes | Yes | Yes | No | 241+---------------------+-----------------+---------------+----------+----------------+--------------+ 242| FVP_SSE300_MPS3 | No | Yes | Yes | Yes | No | 243+---------------------+-----------------+---------------+----------+----------------+--------------+ 244| Corstone-310 FVP | Yes | Yes | Yes | Yes | No | 245+---------------------+-----------------+---------------+----------+----------------+--------------+ 246| LPC55S69 | Yes | Yes | No | Yes | No | 247+---------------------+-----------------+---------------+----------+----------------+--------------+ 248| Musca-B1 | Yes | Yes | Yes | Yes | No | 249+---------------------+-----------------+---------------+----------+----------------+--------------+ 250| Musca-S1 | Yes | Yes | Yes | Yes | No | 251+---------------------+-----------------+---------------+----------+----------------+--------------+ 252| AN524 | Yes | No | No | Yes | No | 253+---------------------+-----------------+---------------+----------+----------------+--------------+ 254| AN547 | No | Yes | Yes | Yes | No | 255+---------------------+-----------------+---------------+----------+----------------+--------------+ 256| AN552 | No | Yes | Yes | Yes | No | 257+---------------------+-----------------+---------------+----------+----------------+--------------+ 258| PSoC64 | Yes | No | No | No | No | 259+---------------------+-----------------+---------------+----------+----------------+--------------+ 260| STM_DISCO_L562QE | No | Yes | No | No | No | 261+---------------------+-----------------+---------------+----------+----------------+--------------+ 262| STM_NUCLEO_L552ZE_Q | No | Yes | No | No | No | 263+---------------------+-----------------+---------------+----------+----------------+--------------+ 264| nRF9160 DK | Yes | Yes | No | No | No | 265+---------------------+-----------------+---------------+----------+----------------+--------------+ 266| nRF5340 DK | Yes | Yes | No | No | No | 267+---------------------+-----------------+---------------+----------+----------------+--------------+ 268| BL5340 DVK | Yes | Yes | Yes | No | No | 269+---------------------+-----------------+---------------+----------+----------------+--------------+ 270| RSS | No | No | No | No | Yes | 271+---------------------+-----------------+---------------+----------+----------------+--------------+ 272 273.. [1] To disable BL2, please set the ``BL2`` cmake option to ``OFF`` 274 275.. [2] BL2 is enabled by default 276 277.. [3] The image executes in-place (XIP) and is in Overwrite mode for image 278 update by default 279 280.. [4] To enable XIP Swap mode, assign the "SWAP_USING_SCRATCH" or 281 "SWAP_USING_MOVE" string to the ``MCUBOOT_UPGRADE_STRATEGY`` 282 configuration variable in the build configuration file, or include this 283 macro definition in the command line 284 285.. [5] To enable direct-xip, assign the "DIRECT_XIP" string to the 286 ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build 287 configuration file, or include this macro definition in the command line 288 289.. [6] To enable RAM load, assign the "RAM_LOAD" string to the 290 ``MCUBOOT_UPGRADE_STRATEGY`` configuration variable in the build 291 configuration file, or include this macro definition in the command line 292 293******************* 294Multiple image boot 295******************* 296It is possible to update the firmware images independently to support the 297scenario when secure and non-secure images are provided by different vendors. 298Multiple image boot is supported only together with the overwrite and swap 299firmware upgrade modes. 300 301It is possible to describe the dependencies of the images on each other in 302order to avoid a faulty upgrade when incompatible versions would be installed. 303These dependencies are part of the image manifest area. 304The dependencies are composed from two parts: 305 306 - **Image identifier:** The number of the image which the current image (whose 307 manifest area contains the dependency entry) depends on. The image identifier 308 starts from 0. 309 310 - **Minimum version:** The minimum version of other image must be present on 311 the device by the end of the upgrade (both images might be updated at the 312 same time). 313 314Dependencies can be added to the images at compile time with the following 315compile time switches: 316 317 - ``MCUBOOT_S_IMAGE_MIN_VER`` It is added to the non-secure image and specifies the 318 minimum required version of the secure image. 319 - ``MCUBOOT_NS_IMAGE_MIN_VER`` It is added to the secure image and specifies the 320 minimum required version of the non-secure image. 321 322Example of how to provide the secure image minimum version:: 323 324 cmake -DTFM_PLATFORM=arm/musca_b1 -DMCUBOOT_S_IMAGE_MIN_VER=1.2.3+4 .. 325 326******************** 327Signature algorithms 328******************** 329MbedTLS library is used to sign the images. The list of supported signing 330algorithms: 331 332 - `RSA-2048` 333 - `RSA-3072`: default 334 335Example keys stored in: 336 337 - ``root-RSA-2048.pem`` : Used to sign single image (S+NS) or secure image 338 in case of multiple image boot 339 - ``root-RSA-2048_1.pem`` : Used to sign non-secure image in case of multiple 340 image boot 341 - ``root-RSA-3072.pem`` : Used to sign single image (S+NS) or secure image 342 in case of multiple image boot 343 - ``root-RSA-3072_1.pem`` : Used to sign non-secure image in case of multiple 344 image boot 345 346************************ 347Build time configuration 348************************ 349MCUBoot related compile time switches can be set by cmake variables. 350 351- BL2 (default: True): 352 - **True:** TF-M built together with bootloader. MCUBoot is executed after 353 reset and it authenticates TF-M and starts secure code. 354 - **False:** TF-M built without bootloader. Secure image linked to the 355 beginning of the device memory and executed after reset. If it is false 356 then using any of the further compile time switches is invalid. 357- MCUBOOT_UPGRADE_STRATEGY (default: "OVERWRITE_ONLY"): 358 - **"OVERWRITE_ONLY":** Default firmware upgrade operation with overwrite. 359 - **"SWAP_USING_SCRATCH":** Activate swapping firmware upgrade operation 360 with a scratch area in flash 361 - **"SWAP_USING_MOVE":** Activate swapping firmware upgrade operation 362 without a scratch area in flash 363 - **"DIRECT_XIP":** Activate direct execute-in-place firmware upgrade 364 operation. 365 - **"RAM_LOAD":** Activate RAM loading firmware upgrade operation, where 366 the latest image is copied to RAM and runs from there instead of being 367 executed in-place. 368- MCUBOOT_SIGNATURE_TYPE (default: RSA-3072): 369 - **RSA-2048:** Image is signed with RSA algorithm and signed with 2048 bit key. 370 - **RSA-3072:** Image is signed with RSA algorithm and signed with 3072 bit key. 371 - **EC-P256:** Image is signed with ECDSA P-256 algorithm. 372 - **EC-P384:** Image is signed with ECDSA P-384 algorithm. 373- MCUBOOT_IMAGE_NUMBER (default: 2): 374 - **1:** Single image boot, secure and non-secure images are signed and 375 updated together. 376 - **2:** Multiple image boot, secure and non-secure images are signed and 377 updatable independently. 378- MCUBOOT_HW_KEY (default: True): 379 - **True:** The hash of public key is provisioned to the SoC and the image 380 manifest contains the whole public key (imgtool uses 381 ``--public_key_format=full``). MCUBoot validates the key before using it 382 for firmware authentication, it calculates the hash of public key from the 383 manifest and compare against the retrieved key-hash from the hardware. 384 This way MCUBoot is independent from the public key(s). Key(s) can be 385 provisioned any time and by different parties. 386 - **False:** The whole public key is embedded to the bootloader code and the 387 image manifest contains only the hash of the public key (imgtool uses 388 ``--public_key_format=hash``). MCUBoot validates the key before using it 389 for firmware authentication, it calculates the hash of built-in public key 390 and compare against the retrieved key-hash from the image manifest. After 391 this the bootloader can verify that the image was signed with a private 392 key that corresponds to the retrieved key-hash (it can have more public 393 keys embedded in and it may have to look for the matching one). All the 394 public key(s) must be known at MCUBoot build time. 395- MCUBOOT_LOG_LEVEL: 396 Can be used to configure the level of logging in MCUBoot. The possible 397 values are the following: 398 399 - **OFF** 400 - **ERROR** 401 - **WARNING** 402 - **INFO** 403 - **DEBUG** 404 405 The logging in MCUBoot can be disabled and thus the code size can be reduced 406 by setting it to ``OFF``. Its value depends on the build type. If the build 407 type is ``Debug`` then default value is ``INFO``. In case of different kinds 408 of ``Release`` builds the default value is ``OFF``. The default value can 409 be overridden through the command line or in the CMake GUI regardless of the 410 build type. 411- MCUBOOT_ENC_IMAGES (default: False): 412 - **True:** Adds encrypted image support in the source and encrypts the 413 resulting image using the ``enc-rsa2048-pub.pem`` key found in the MCUBoot 414 repository. 415 - **False:** Doesn't add encrypted image support and doesn't encrypt the 416 image. 417 418 .. Note:: 419 The decryption takes place during the upgrade process, when the images 420 are being moved between the slots. This means that boards that don't 421 already have an image on them with MCUBoot that has been compiled with 422 ``MCUBOOT_ENCRYPT_RSA`` enabled need special treatment. In order to load 423 an encrypted image to such boards, an upgrade needs to be executed. This 424 can be done by using MCUBoot, putting an image in the secondary image 425 area, and setting ``MCUBOOT_ENCRYPT_RSA`` to ``ON``. When using the 426 ``OVERWRITE_ONLY`` upgrade strategy, this is enough. When using 427 ``SWAP_USING_SCRATCH`` or ``SWAP_USING_MOVE``, an image is needed in 428 the primary image area as well, to trigger the update. 429 430 .. Danger:: 431 DO NOT use the ``enc-rsa2048-pub.pem`` key in production code, it is 432 exclusively for testing! 433 434Image versioning 435================ 436An image version number is written to its header by one of the Python scripts, 437and this number is used by the bootloader when the direct execute-in-place or 438the RAM loading mode is enabled. It is also used in case of multiple image boot 439when the bootloader checks the image dependencies if any have been added to the 440images. 441 442The version number of the image (single image boot) can manually be passed in 443through the command line in the cmake configuration step:: 444 445 cmake -DTFM_PLATFORM=arm/musca_b1 -DIMAGE_VERSION_S=1.2.3+4 .. 446 447Alternatively, the version number can be less specific (e.g 1, 1.2, or 1.2.3), 448where the missing numbers are automatically set to zero. The image version 449number argument is optional, and if it is left out, then the version numbers of 450the image(s) being built in the same directory will automatically change. In 451this case, the last component (the build number) automatically increments from 452the previous one: 0.0.0+1 -> 0.0.0+2, for as many times as the build is re-ran, 453**until a number is explicitly provided**. If automatic versioning is in place 454and then an image version number is provided for the first time, the new number 455will take precedence and be used instead. All subsequent image versions are 456then set to the last number that has been specified, and the build number would 457stop incrementing. Any new version numbers that are provided will overwrite 458the previous one: 0.0.0+1 -> 0.0.0+2. Note: To re-apply automatic image 459versioning, please start a clean build without specifying the image version 460number at all. In case of multiple image boot there are separate compile time 461switches for both images to provide their version: ``IMAGE_VERSION_S`` and 462``IMAGE_VERSION_NS``. These must be used instead of ``IMAGE_VERSION_S``. 463 464Security counter 465================ 466Each signed image contains a security counter in its manifest. It is used by the 467bootloader and its aim is to have an independent (from the image version) 468counter to ensure rollback protection by comparing the new image's security 469counter against the original (currently active) image's security counter during 470the image upgrade process. It is added to the manifest (to the TLV area that is 471appended to the end of the image) by one of the Python scripts when signing the 472image. The value of the security counter is security critical data and it is in 473the integrity protected part of the image. The last valid security counter 474should always be stored in a non-volatile and trusted component of the device 475and its value should always be increased if a security flaw was fixed in the 476current image version. The value of the security counter (single image boot) can 477be specified at build time in the cmake configuration step:: 478 479 cmake -DTFM_PLATFORM=arm/musca_b1 -DSECURITY_COUNTER_S=42 ../ 480 481The security counter can be independent from the image version, but not 482necessarily. Alternatively, if it is not specified at build time with the 483``SECURITY_COUNTER`` option the Python script will automatically generate it 484from the image version number (not including the build number) and this value 485will be added to the signed image. In case of multiple image boot there are 486separate compile time switches for both images to provide their security counter 487value: ``SECURITY_COUNTER_S`` and ``SECURITY_COUNTER_NS``. These must be used 488instead of ``SECURITY_COUNTER_S``. If these are not defined then the security 489counter values will be derived from the corresponding image version similar to 490the single image boot. 491 492*************************** 493Signing the images manually 494*************************** 495Normally the build system handles the signing (computing hash over the image 496and security critical manifest data and then signing the hash) of the firmware 497images. However, the images also can be signed manually by using the ``imgtool`` 498Python program which is located in the MCUboot repository in the ``scripts`` 499folder or can be installed with the pip package manager. 500Issue the ``python3 imgtool.py sign --help`` command in the directory for more 501information about the mandatory and optional arguments. The tool takes an image 502in binary or Intel Hex format and adds a header and trailer that MCUBoot is 503expecting. In case of single image boot after a successful build the 504``tfm_s_ns.bin`` build artifact (contains the concatenated secure and non-secure 505images) must be passed to the script and in case of multiple image boot the 506``tfm_s.bin`` and ``tfm_ns.bin`` binaries can be passed to prepare the signed 507images. 508 509Signing the secure image manually in case of multiple image boot 510================================================================ 511 512:: 513 514 python3 bl2/ext/mcuboot/scripts/imgtool.py sign \ 515 --layout <build_dir>/bl2/ext/mcuboot/CMakeFiles/signing_layout_s.dir/signing_layout_s.c.obj \ 516 -k <tfm_dir>/bl2/ext/mcuboot/root-RSA-3072.pem \ 517 --public-key-format full \ 518 --align 1 \ 519 -v 1.2.3+4 \ 520 -d "(1,1.2.3+0)" \ 521 -s 42 \ 522 -H 0x400 \ 523 <build_dir>/bin/tfm_s.bin \ 524 <build_dir>/bin/tfm_s_signed.bin 525 526************************ 527Testing firmware upgrade 528************************ 529As downloading the new firmware image is out of scope for MCUBoot, the update 530process is started from a state where the original and the new image are already 531programmed to the appropriate memory slots. To generate the original and a new 532firmware package, TF-M is built twice with different build configurations. 533 534Overwriting firmware upgrade 535============================ 536Run TF-M build twice with ``MCUBOOT_IMAGE_NUMBER`` set to "1" in both cases 537(single image boot), but with two different build configurations: default and 538regression. Save the artifacts between builds, because second run can overwrite 539original binaries. Download default build to the primary slot and regression 540build to the secondary slot. 541 542Executing firmware upgrade on FVP_MPS2_AEMv8M 543--------------------------------------------- 544.. code-block:: bash 545 546 <ARM_DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \ 547 --parameter fvp_mps2.platform_type=2 \ 548 --parameter cpu0.baseline=0 \ 549 --parameter cpu0.INITVTOR_S=0x10000000 \ 550 --parameter cpu0.semihosting-enable=0 \ 551 --parameter fvp_mps2.DISABLE_GATING=0 \ 552 --parameter fvp_mps2.telnetterminal0.start_telnet=1 \ 553 --parameter fvp_mps2.telnetterminal1.start_telnet=0 \ 554 --parameter fvp_mps2.telnetterminal2.start_telnet=0 \ 555 --parameter fvp_mps2.telnetterminal0.quiet=0 \ 556 --parameter fvp_mps2.telnetterminal1.quiet=1 \ 557 --parameter fvp_mps2.telnetterminal2.quiet=1 \ 558 --application cpu0=<build_dir>/bin/bl2.axf \ 559 --data cpu0=<default_build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 \ 560 --data cpu0=<regresssion_build_dir>/bin/tfm_s_ns_signed.bin@0x10180000 561 562Executing firmware upgrade on SSE 200 FPGA on MPS2 board 563-------------------------------------------------------- 564 565:: 566 567 TITLE: Versatile Express Images Configuration File 568 [IMAGES] 569 TOTALIMAGES: 3 ;Number of Images (Max: 32) 570 IMAGE0ADDRESS: 0x00000000 571 IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader 572 IMAGE1ADDRESS: 0x10080000 573 IMAGE1FILE: \Software\tfm_sig1.bin ; TF-M default test binary blob 574 IMAGE2ADDRESS: 0x10180000 575 IMAGE2FILE: \Software\tfm_sig2.bin ; TF-M regression test binary blob 576 577The following message will be shown in case of successful firmware upgrade: 578 579:: 580 581 [INF] Starting bootloader 582 [INF] Swap type: test 583 [INF] Image upgrade secondary slot -> primary slot 584 [INF] Erasing the primary slot 585 [INF] Copying the secondary slot to the primary slot: 0x100000 bytes 586 [INF] Bootloader chainload address offset: 0x80000 587 [INF] Jumping to the first image slot 588 [Sec Thread] Secure image initializing! 589 590 #### Execute test suites for the Secure area #### 591 Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... 592 ... 593 594To update the secure and non-secure images separately (multiple image boot), 595set the ``MCUBOOT_IMAGE_NUMBER`` switch to "2" (this is the default 596configuration value) and follow the same instructions as in case of single image 597boot. 598 599Executing multiple firmware upgrades on SSE 200 FPGA on MPS2 board 600------------------------------------------------------------------ 601 602:: 603 604 TITLE: Versatile Express Images Configuration File 605 [IMAGES] 606 TOTALIMAGES: 4 ;Number of Images (Max: 32) 607 IMAGE0ADDRESS: 0x00000000 608 IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader 609 IMAGE1ADDRESS: 0x10080000 610 IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob 611 IMAGE2ADDRESS: 0x10180000 612 IMAGE2FILE: \Software\tfm_ss1.bin ; TF-M regression test secure (signed) image 613 IMAGE3ADDRESS: 0x10200000 614 IMAGE3FILE: \Software\tfm_nss1.bin ; TF-M regression test non-secure (signed) image 615 616Note that both the concatenated binary blob (the images are signed separately 617and then concatenated) and the separate signed images can be downloaded to the 618device because on this platform (AN521) both the primary slots and the secondary 619slots are contiguous areas in the Flash (see `Integration with TF-M`_). The 620following message will be shown in case of successful firmware upgrades: 621 622:: 623 624 [INF] Starting bootloader 625 [INF] Swap type: test 626 [INF] Swap type: test 627 [INF] Image upgrade secondary slot -> primary slot 628 [INF] Erasing the primary slot 629 [INF] Copying the secondary slot to the primary slot: 0x80000 bytes 630 [INF] Image upgrade secondary slot -> primary slot 631 [INF] Erasing the primary slot 632 [INF] Copying the secondary slot to the primary slot: 0x80000 bytes 633 [INF] Bootloader chainload address offset: 0x80000 634 [INF] Jumping to the first image slot 635 [Sec Thread] Secure image initializing! 636 TFM level is: 1 637 [Sec Thread] Jumping to non-secure code... 638 639 #### Execute test suites for the Secure area #### 640 Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... 641 ... 642 643Swapping firmware upgrade 644============================= 645Follow the same instructions and platform related configurations as in case of 646overwriting build including these changes: 647 648- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "SWAP" 649 before build. 650- Set the ``MCUBOOT_IMAGE_NUMBER`` compile time switch to "1" (single image 651 boot) or "2" (multiple image boot) before build. 652 653During single image boot the following message will be shown in case of 654successful firmware upgrade, ``Swap type: test`` indicates that images were 655swapped: 656 657:: 658 659 [INF] Starting bootloader 660 [INF] Image 0: magic= good, copy_done=0x3, image_ok=0x3 661 [INF] Scratch: magic= bad, copy_done=0x0, image_ok=0x2 662 [INF] Boot source: primary slot 663 [INF] Swap type: test 664 [INF] Bootloader chainload address offset: 0x80000 665 [INF] Jumping to the first image slot 666 [Sec Thread] Secure image initializing! 667 668 #### Execute test suites for the Secure area #### 669 Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... 670 ... 671 672Direct execute-in-place firmware upgrade 673======================================== 674Follow the same instructions and platform related configurations as in case of 675overwriting build including these changes: 676 677- Set the ``MCUBOOT_UPGRADE_STRATEGY`` compile time switch to "DIRECT_XIP" 678 before build. 679- set ``MCUBOOT_EXECUTION_SLOT`` to ``1`` in the regression build dir. 680- Make sure the image version number was increased between the two build runs 681 either by specifying it manually or by checking in the build log that it was 682 incremented automatically. 683 684Executing firmware upgrade on FVP_MPS2_AEMv8M 685--------------------------------------------- 686 687.. code-block:: bash 688 689 <ARM_DS_PATH>/sw/models/bin/FVP_MPS2_AEMv8M \ 690 --parameter fvp_mps2.platform_type=2 \ 691 --parameter cpu0.baseline=0 \ 692 --parameter cpu0.INITVTOR_S=0x10000000 \ 693 --parameter cpu0.semihosting-enable=0 \ 694 --parameter fvp_mps2.DISABLE_GATING=0 \ 695 --parameter fvp_mps2.telnetterminal0.start_telnet=1 \ 696 --parameter fvp_mps2.telnetterminal1.start_telnet=0 \ 697 --parameter fvp_mps2.telnetterminal2.start_telnet=0 \ 698 --parameter fvp_mps2.telnetterminal0.quiet=0 \ 699 --parameter fvp_mps2.telnetterminal1.quiet=1 \ 700 --parameter fvp_mps2.telnetterminal2.quiet=1 \ 701 --application cpu0=<build_dir>/bin/bl2.axf \ 702 --data cpu0=<default_build_dir>/bin/tfm_s_ns_signed.bin@0x10080000 \ 703 --data cpu0=<regresssion_build_dir>/bin/tfm_s_ns_signed.bin@0x10180000 704 705Executing firmware upgrade on SSE 200 FPGA on MPS2 board 706-------------------------------------------------------- 707 708:: 709 710 TITLE: Versatile Express Images Configuration File 711 [IMAGES] 712 TOTALIMAGES: 3 ;Number of Images (Max: 32) 713 IMAGE0ADDRESS: 0x00000000 714 IMAGE0FILE: \Software\bl2.axf ; BL2 bootloader 715 IMAGE1ADDRESS: 0x10080000 716 IMAGE1FILE: \Software\tfm_sign.bin ; TF-M default test binary blob 717 IMAGE2ADDRESS: 0x10180000 718 IMAGE2FILE: \Software\tfm_sig1.bin ; TF-M regression test binary blob 719 720Executing firmware upgrade on Musca-B1 and Musca-S1 boards 721---------------------------------------------------------- 722After the two images have been built, they can be concatenated to create the 723combined image using ``srec_cat``: 724 725- Linux:: 726 727 srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel 728 729- Windows:: 730 731 srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign.bin -Binary -offset 0xA020000 tfm_sign_1.bin -Binary -offset 0xA100000 -o tfm.hex -Intel 732 733The following message will be shown in case of successful firmware upgrade, 734notice that image with higher version number (``version=1.2.3.5``) is executed: 735 736:: 737 738 [INF] Starting bootloader 739 [INF] Image 0: version=1.2.3.4, magic= good, image_ok=0x3 740 [INF] Image 1: version=1.2.3.5, magic= good, image_ok=0x3 741 [INF] Booting image from the secondary slot 742 [INF] Bootloader chainload address offset: 0xa0000 743 [INF] Jumping to the first image slot 744 [Sec Thread] Secure image initializing! 745 746 #### Execute test suites for the Secure area #### 747 Running Test Suite PSA protected storage S interface tests (TFM_PS_TEST_2XXX)... 748 ... 749 750Executing firmware upgrade on CoreLink SSE-200 Subsystem for MPS3 (AN524) 751------------------------------------------------------------------------- 752 753:: 754 755 TITLE: Arm MPS3 FPGA prototyping board Images Configuration File 756 757 [IMAGES] 758 TOTALIMAGES: 3 ;Number of Images (Max: 32) 759 760 IMAGE0UPDATE: AUTO ;Image Update:NONE/AUTO/FORCE 761 IMAGE0ADDRESS: 0x00000000 762 IMAGE0FILE: \SOFTWARE\bl2.bin ;BL2 bootloader 763 IMAGE1UPDATE: AUTO 764 IMAGE1ADDRESS: 0x00040000 765 IMAGE1FILE: \SOFTWARE\tfm_sig0.bin ;TF-M example application binary blob 766 IMAGE2UPDATE: AUTO 767 IMAGE2ADDRESS: 0x000C0000 768 IMAGE2FILE: \SOFTWARE\tfm_sig1.bin ;TF-M regression test binary blob 769 770RAM loading firmware upgrade 771============================ 772To enable RAM loading, please set ``MCUBOOT_UPGRADE_STRATEGY`` to "RAM_LOAD" 773(either in the configuration file or through the command line), and then specify 774a destination load address in RAM where the image can be copied to and executed 775from. The ``S_IMAGE_LOAD_ADDRESS`` macro must be specified in the target 776dependent files, and if multiple image boot is enabled then 777``NS_IMAGE_LOAD_ADDRESS`` must also be defined. For example with Musca-S, its 778``flash_layout.h`` file in the ``platform`` folder should include ``#define 779S_IMAGE_LOAD_ADDRESS #0xA0020000`` 780 781Executing firmware upgrade on Musca-S board 782-------------------------------------------- 783After two images have been built, they can be concatenated to create the 784combined image using ``srec_cat``: 785 786- Linux:: 787 788 srec_cat bin/bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel 789 790- Windows:: 791 792 srec_cat.exe bin\bl2.bin -Binary -offset 0xA000000 tfm_sign_old.bin -Binary -offset 0xA020000 tfm_sign_new.bin -Binary -offset 0xA100000 -o tfm.hex -Intel 793 794The following message will be shown in case of successful firmware upgrade when, 795RAM loading is enabled, notice that image with higher version number 796(``version=0.0.0.2``) is executed: 797 798:: 799 800 [INF] Starting bootloader 801 [INF] Image 0: version=0.0.0.1, magic= good, image_ok=0x3 802 [INF] Image 1: version=0.0.0.2, magic= good, image_ok=0x3 803 [INF] Image has been copied from the secondary slot in flash to SRAM address 0xA0020000 804 [INF] Booting image from SRAM at address 0xA0020000 805 [INF] Bootloader chainload address offset: 0x20000 806 [INF] Jumping to the first image slot 807 [Sec Thread] Secure image initializing! 808 809-------------- 810 811**************************************** 812Integration with Firmware Update service 813**************************************** 814The shim layer of the Firmware Update partition calls the APIs in 815bootutil_misc.c to control the image status. 816 817- Call ``boot_set_pending_multi()`` to make the image as a candidate image for 818 booting. 819- Call ``boot_set_confirmed_multi()`` to make the image as a permanent image. 820 821.. Note:: 822 Currently, in direct-xip mode and ram-load mode, TF-M cannot get the 823 information of which slot contains the running image from the bootloader. 824 So the Firmware Update partition cannot decide where to write the new 825 image. As a result, the firmware update service is not supported in 826 direct-xip mode and ram-load mode. 827 828*Copyright (c) 2018-2023, Arm Limited. All rights reserved.* 829
