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