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