doc/design.txt

#
# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
# 
#  http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
#

****** BOOT LOADER

*** SUMMARY

mcuboot comprises two packages:

    * The bootutil library (boot/bootutil)
    * The boot application (each port has its own at boot/<port>)

The bootutil library performs most of the functions of a boot loader.  In
particular, the piece that is missing is the final step of actually jumping to
the main image.  This last step is instead implemented by the boot application.
Boot loader functionality is separated in this manner to enable unit testing of
the boot loader.  A library can be unit tested, but an application can't.
Therefore, functionality is delegated to the bootutil library when possible.

*** LIMITATIONS

The boot loader currently only supports images with the following
characteristics:
    * Built to run from flash.
    * Build to run from a fixed location (i.e., not position-independent).

*** IMAGE FORMAT

The following definitions describe the image format.

#define IMAGE_MAGIC                 0x96f3b83c

#define IMAGE_HEADER_SIZE           32

struct image_version {
    uint8_t iv_major;
    uint8_t iv_minor;
    uint16_t iv_revision;
    uint32_t iv_build_num;
};

/** Image header.  All fields are in little endian byte order. */
struct image_header {
    uint32_t ih_magic;
    uint16_t ih_tlv_size; /* Combined size of trailing TLVs (bytes). */
    uint8_t  ih_key_id;   /* Which key image is signed with (0xff=unsigned). */
    uint8_t  _pad1;
    uint16_t ih_hdr_size; /* Size of image header (bytes). */
    uint16_t _pad2;
    uint32_t ih_img_size; /* Does not include header. */
    uint32_t ih_flags;    /* IMAGE_F_[...] */
    struct image_version ih_ver;
    uint32_t _pad3;
};

/** Image trailer TLV format. All fields in little endian. */
struct image_tlv {
    uint8_t  it_type;   /* IMAGE_TLV_[...]. */
    uint8_t  _pad;
    uint16_t it_len     /* Data length (not including TLV header). */
};

/*
 * Image header flags.
 */
#define IMAGE_F_PIC                   0x00000001 /* Not currently supported. */
#define IMAGE_F_SHA256                0x00000002 /* Image contains hash TLV */
#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 /* PKCS15 w/RSA and SHA */
#define IMAGE_F_ECDSA224_SHA256       0x00000008 /* ECDSA256 over SHA256 */
#define IMAGE_F_NON_BOOTABLE          0x00000010 /* Split image app. */
#define IMAGE_F_ECDSA256_SHA256       0x00000020 /* ECDSA256 over SHA256 */

/*
 * Image trailer TLV types.
 */
#define IMAGE_TLV_SHA256            1   /* SHA256 of image hdr and body */
#define IMAGE_TLV_RSA2048           2   /* RSA2048 of hash output */
#define IMAGE_TLV_ECDSA224          3   /* ECDSA of hash output */
#define IMAGE_TLV_ECDSA256          4   /* ECDSA of hash output */

Optional type-length-value records (TLVs) containing image metadata are placed
after the end of the image.

The ih_hdr_size field indicates the length of the header, and therefore the
offset of the image itself.  This field provides for backwards compatibility in
case of changes to the format of the image header.

*** FLASH MAP

A device's flash is partitioned according to its _flash map_.  At a high
level, the flash map maps numeric IDs to _flash areas_.  A flash area is a
region of disk with the following properties:
    (1) An area can be fully erased without affecting any other areas.
    (2) A write to one area does not restrict writes to other areas.

The boot loader uses the following flash areas:

#define FLASH_AREA_BOOTLOADER                    0
#define FLASH_AREA_IMAGE_0                       1
#define FLASH_AREA_IMAGE_1                       2
#define FLASH_AREA_IMAGE_SCRATCH                 3

*** IMAGE SLOTS

A portion of the flash memory is partitioned into two image slots: a primary
slot (0) and a secondary slot (1).  The boot loader will only run an image from
the primary slot, so images must be built such that they can run from that
fixed location in flash.  If the boot loader needs to run the image resident in
the secondary slot, it must swap the two images in flash prior to booting.

In addition to the two image slots, the boot loader requires a scratch area to
allow for reliable image swapping.

*** BOOT STATES

Logically, you can think of a pair of values associated with each image slot:
pending and confirmed.  On startup, the boot loader determines the state of the
device by inspecting each pair of values.  These values have the following
meanings:

* pending: Indicates whether the image should be used on the next reboot; can
  hold one of three values:
    " " (unset):     Don't use image on next boot
    "T" (temporary): Use image on next boot; absent subsequent confirm command,
                     revert to original image on second reboot.
    "P" (permanent): Use image on next boot and all subsequent boots

* confirmed: always use image unless excluded by a test image.

In English, when the user wants to run the secondary image, they set the
pending flag for the second slot and reboot the device.  On startup, the boot
loader will swap the two images in flash, clear the secondary slot's pending
flag, and run the newly-copied image in slot 0.  If the user set the pending
flag to "temporary," then this is only a temporary state; if the device reboots
again, the boot loader swaps the images back to their original slots and boots
into the original image.  If the user doesn't want to revert to the original
state, they can make the current state permanent by setting the confirmed flag
in slot 0.

Switching to an alternate image is a two-step process (set + confirm) to
prevent a device from becoming "bricked" by bad firmware.  If the device
crashes immediately upon booting the second image, the boot loader reverts to
the working image, rather than repeatedly rebooting into the bad image.

Alternatively, if the user is confident that the second image is good, they can
set and confirm in a single action by setting the pending flag to "permanent."

The following set of tables illustrate the four possible states that the device
can be in:

                   | slot-0 | slot-1 |
    ---------------+--------+--------|
           pending |        |        |
         confirmed |   X    |        |
    ---------------+--------+--------'
    Image 0 confirmed;               |
    No change on reboot              |
    ---------------------------------'

                   | slot-0 | slot-1 |
    ---------------+--------+--------|
           pending |        |   T    |
         confirmed |   X    |        |
    ---------------+--------+--------'
    Image 0 confirmed;               |
    Test image 1 on next reboot      |
    ---------------------------------'

                   | slot-0 | slot-1 |
    ---------------+--------+--------|
           pending |        |   P    |
         confirmed |   X    |        |
    ---------------+--------+--------'
    Image 0 confirmed;               |
    Use image 1 permanently on boot  |
    ---------------------------------'

                   | slot-0 | slot-1 |
    ---------------+--------+--------|
           pending |        |        |
         confirmed |        |   X    |
    ---------------+--------+--------'
    Testing image 0;                 |
    Revert to image 1 on next reboot |
    ---------------------------------'

*** IMAGE TRAILER

For the bootloader to be able to determine the current state and what actions
should be taken during the current boot operation, it uses metadata existing
on both slots, and while doing a swap operation it can be located in scratch.
This metadata is located at the end of the slot and is called image trailer.
An image trailer has the following structure:

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    ~                                                               ~
    ~             Swap status (128 * min-write-size * 3)            ~
    ~                                                               ~
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |   Copy done   |           0xff padding (7 octets)             |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |   Image OK    |           0xff padding (7 octets)             |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                       MAGIC (16 octets)                       |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

These records are at the end of each image slot.  The offset immediately
following such a record represents the start of the next flash area.

Note: "min-write-size" is a property of the flash hardware.  If the hardware
allows individual bytes to be written at arbitrary addresses, then
min-write-size is 1.  If the hardware only allows writes at even addresses,
then min-write-size is 2, and so on.

The fields are defined as follows:

1. Swap status: A series of single-byte records.  Each record corresponds to a
flash sector in an image slot.  A swap status byte indicate the location of
the corresponding sector data.  During an image swap, image data is moved one
sector at a time.  The swap status is necessary for resuming a swap operation
if the device rebooted before a swap operation completed.

2. Copy done: A single byte indicating whether the image in this slot is
complete (0x01=done; 0xff=not done).

3. Image OK: A single byte indicating whether the image in this slot has been
confirmed as good by the user (0x01=confirmed; 0xff=not confirmed).

4. MAGIC: The following 16 bytes, written in host-byte-order:

    const uint32_t boot_img_magic[4] = {
        0xf395c277,
        0x7fefd260,
        0x0f505235,
        0x8079b62c,
    };

*** IMAGE TRAILERS

At startup, the boot loader determines which of the above four states the
device is in by inspecting the image trailers.  When using the term "image
trailers" what is meant is the aggregate information provided by both image
slot's trailers.

The image trailers records are structured around the limitations imposed by flash
hardware.  As a consequence, they do not have a very intuitive design, and it
is difficult to get a sense of the state of the device just by looking at the
image trailers.  It is better to map all the possible trailer states to the four
states described above via a set of tables.  These tables are reproduced below.
In these tables, the "pending" and "confirmed" flags are shown for illustrative
purposes; they are not actually present in the image trailers.

Note: An important caveat about the tables described below is that they must
be evaluated in the order presented here. Lower state numbers must have a
higher priority when testing the image trailers.


    State I
                     | slot-0 | slot-1 |
    -----------------+--------+--------|
               magic | Any    | Good   |
            image-ok | Any    | Unset  |
           copy-done | Any    | Any    |
    -----------------+--------+--------'
             pending |        |   T    |
          confirmed  |   X    |        |
    -----------------+--------+--------'
     swap: test                        |
    -----------------------------------'


    State II
                     | slot-0 | slot-1 |
    -----------------+--------+--------|
               magic | Any    | Good   |
            image-ok | Any    | 0x01   |
           copy-done | Any    | Any    |
    -----------------+--------+--------'
             pending |        |   P    |
          confirmed  |   X    |        |
    -----------------+--------+--------'
     swap: permanent                   |
    -----------------------------------'


    State III
                     | slot-0 | slot-1 |
    -----------------+--------+--------|
               magic | Good   | Unset  |
            image-ok | 0xff   | Any    |
           copy-done | 0x01   | Any    |
    -----------------+--------+--------'
             pending |        |        |
          confirmed  |        |   X    |
    -----------------+--------+--------'
     swap: revert (test image running) |
    -----------------------------------'


Those three states described above are explicity tested for and result in a
swap decision by the bootloader. If the existing values in the the image trailers
are not one of those previously described the bootloader will assume no swap
operation is to be performed which is illustrated by state IV.


    State IV
                     | slot-0 | slot-1 |
    -----------------+--------+--------|
               magic | Any    | Any    |
            image-ok | Any    | Any    |
           copy-done | Any    | Any    |
    -----------------+--------+--------'
             pending |        |        |
          confirmed  |   X    |        |
    -----------------+--------+--------'
     swap: none                        |
    -----------------------------------'


Note: An important caveat to be mentioned here is, that due to the physical
limitations of the storage and another possible failure, two extra "states"
were added specifically to signal a failure in the boot process.

1. One of them is a result of any device read/write error, called panic and
   will result in the bootloader hanging without booting the image in slot 0.

2. Another state was added specifically to handle the situation in which a swap
   was requested and the image in slot 1 fails to validate, due to hashing
   or signing error. This state behaves as state IV with the extra action of
   marking the image in slot 0 as confirmed.


*** HIGH-LEVEL OPERATION

With the terms defined, we can now explore the boot loader's operation.  First,
a high-level overview of the boot process is presented.  Then, the following
sections describe each step of the process in more detail.

Procedure:

A. Inspect swap status region; is an interrupted swap being resumed?
    Yes: Complete the partial swap operation; skip to step C.
    No: Proceed to step B.

B. Inspect image trailers; is a swap requested?
    Yes.
        1. Is the requested image valid (integrity and security check)?
            Yes.
                a. Perform swap operation.
                b. Persist completion of swap procedure to image trailers.
                c. Proceed to step C.
            No.
                a. Erase invalid image.
                b. Persist failure of swap procedure to image trailers.
                c. Proceed to step C.
    No: Proceed to step C.

C. Boot into image in slot 0.

*** IMAGE SWAPPING

The boot loader swaps the contents of the two image slots for two reasons:
    * User has issued a "set pending" operation; the image in slot-1 should be
      run once (state II) or repeatedly (state III), depending on whether a
      permanent swap was specified.
    * Test image rebooted without being confirmed; the boot loader should
      revert to the original image currently in slot-1 (state IV).

If the image trailers indicates that the image in the secondary slot should be
run, the boot loader needs to copy it to the primary slot.  The image currently
in the primary slot also needs to be retained in flash so that it can be used
later.  Furthermore, both images need to be recoverable if the boot loader
resets in the middle of the swap operation.  The two images are swapped
according to the following procedure:

    1. Determine how many flash sectors each image slot consists of.  This
       number must be the same for both slots.
    2. Iterate the list of sector indices in descending order (i.e., starting
       with the greatest index); current element = "index".
        b. Erase scratch area.
        c. Copy slot0[index] to scratch area.
            - If these are the last sectors (i.e., first swap being perfomed),
              copy the full sector *except* the image trailer.
            - Else, copy entire sector contents.
        d. Write updated swap status (i).

        e. Erase slot1[index]
        f. Copy slot0[index] to slot1[index]
            - If these are the last sectors (i.e., first swap being perfomed),
              copy the full sector *except* the image trailer.
            - Else, copy entire sector contents.
        g. Write updated swap status (ii).

        h. Erase slot0[index].
        i. Copy scratch area slot0[index].
            - If these are the last sectors (i.e., first swap being perfomed),
              copy the full sector *except* the image trailer.
            - Else, copy entire sector contents.
        j. Write updated swap status (iii).

    3. Persist completion of swap procedure to slot 0 image trailer.

The additional caveats in step 2f are necessary so that the slot 1 image
trailer can be written by the user at a later time.  With the image trailer
unwritten, the user can test the image in slot 1 (i.e., transition to state
II).

Note1: If the sector being copied is the last sector, then swap status is
temporarily maintained on scratch for the duration of this operation, always
using slot0's area otherwise.

Note2: The bootloader tries to copy only used sectors (based on largest image
installed on any of the slots), minimizing the amount of sectors copied and
reducing the amount of time required for a swap operation.

The particulars of step 3 vary depending on whether an image is being tested,
permanently used, reverted or a validation failure of slot 1 happened when a
swap was requested:

    * test:
        o Write slot0.copy_done = 1
        (swap caused the following values to be written:
            slot0.magic = BOOT_MAGIC
            slot0.image_ok = Unset)

    * permanent:
        o Write slot0.copy_done = 1
        (swap caused the following values to be written:
            slot0.magic = BOOT_MAGIC
            slot0.image_ok = 0x01)

    * revert:
        o Write slot0.copy_done = 1
        o Write slot0.image_ok = 1
        (swap caused the following values to be written:
            slot0.magic = BOOT_MAGIC)

    * failure to validate slot 1:
        o Write slot0.image_ok = 1

After completing the operations as described above the image in slot 0 should
be booted.

*** SWAP STATUS

The swap status region allows the boot loader to recover in case it restarts in
the middle of an image swap operation.  The swap status region consists of a
series of single-byte records.  These records are written independently, and
therefore must be padded according to the minimum write size imposed by the
flash hardware.  In the below figure, a min-write-size of 1 is assumed for
simplicity.  The structure of the swap status region is illustrated below.  In
this figure, a min-write-size of 1 is assumed for simplicity.

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |sec125,state 2 |                                               |
    +-+-+-+-+-+-+-+-+                                               +
    ~                                                               ~
    ~               [Records for indices 124 through 1              ~
    ~                                                               ~
    ~               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    ~               |sec000,state 0 |sec000,state 1 |sec000,state 2 |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The above is probably not helpful at all; here is a description in English.

Each image slot is partitioned into a sequence of flash sectors.  If we were to
enumerate the sectors in a single slot, starting at 0, we would have a list of
sector indices.  Since there are two image slots, each sector index would
correspond to a pair of sectors.  For example, sector index 0 corresponds to
the first sector in slot 0 and the first sector in slot 1.  Furthermore, we
impose a limit of 128 indices.  If an image slot consists of more than 128
sectors, the flash layout is not compatible with this boot loader.  Finally,
reverse the list of indices such that the list starts with index 127 and ends
with 0.  The swap status region is a representation of this reversed list.

During a swap operation, each sector index transitions through four separate
states:
    0. slot 0: image 0,   slot 1: image 1,   scratch: N/A
    1. slot 0: image 0,   slot 1: N/A,       scratch: image 1 (1->s, erase 1)
    2. slot 0: N/A,       slot 1: image 0,   scratch: image 1 (0->1, erase 0)
    3. slot 0: image 1,   slot 1: image 0,   scratch: N/A     (s->0)

Each time a sector index transitions to a new state, the boot loader writes a
record to the swap status region.  Logically, the boot loader only needs one
record per sector index to keep track of the current swap state.  However, due
to limitations imposed by flash hardware, a record cannot be overwritten when
an index's state changes.  To solve this problem, the boot loader uses three
records per sector index rather than just one.

Each sector-state pair is represented as a set of three records.  The record
values map to the above four states as follows

            | rec0 | rec1 | rec2
    --------+------+------+------
    state 0 | 0xff | 0xff | 0xff
    state 1 | 0x01 | 0xff | 0xff
    state 2 | 0x01 | 0x02 | 0xff
    state 3 | 0x01 | 0x02 | 0x03

The swap status region can accommodate 128 sector indices.  Hence, the size of
the region, in bytes, is 128 * min-write-size * 3.  The number 128 is chosen
somewhat arbitrarily and will likely be made configurable.  The only
requirement for the index count is that is is great enough to account for a
maximum-sized image (i.e., at least as great as the total sector count in an
image slot).  If a device's image slots use less than 128 sectors, the first
record that gets written will be somewhere in the middle of the region.  For
example, if a slot uses 64 sectors, the first sector index that gets swapped is
63, which corresponds to the exact halfway point within the region.

Note: since the scratch area only ever needs to record swapping of the last
sector, it uses at most min-write-size * 3 bytes for its own status area.

*** RESET RECOVERY

If the boot loader resets in the middle of a swap operation, the two images may
be discontiguous in flash.  Bootutil recovers from this condition by using the
image trailers to determine how the image parts are distributed in flash.

The first step is determine where the relevant swap status region is located.
Because this region is embedded within the image slots, its location in flash
changes during a swap operation.  The below set of tables map image trailers
contents to swap status location.  In these tables, the "source" field
indicates where the swap status region is located.

              | slot-0     | scratch    |
    ----------+------------+------------|
        magic | Good       | Any        |
    copy-done | 0x01       | N/A        |
    ----------+------------+------------'
    source: none                        |
    ------------------------------------'
    
              | slot-0     | scratch    |
    ----------+------------+------------|
        magic | Good       | Any        |
    copy-done | 0xff       | N/A        |
    ----------+------------+------------'
    source: slot 0                      |
    ------------------------------------'
    
              | slot-0     | scratch    |
    ----------+------------+------------|
        magic | Any        | Good       |
    copy-done | Any        | N/A        |
    ----------+------------+------------'
    source: scratch                     |
    ------------------------------------'
    
              | slot-0     | scratch    |
    ----------+------------+------------|
        magic | Unset      | Any        |
    copy-done | 0xff       | N/A        |
    ----------+------------+------------|
    source: slot 0                      |
    ------------------------------------+------------------------------+
    This represents one of two cases:                                  |
    o No swaps ever (no status to read, so no harm in checking).       |
    o Mid-revert; status in slot 0.                                    |
    For this reason we assume slot 0 as source, to trigger a check     |
    of the status area and find out if there was swapping under way.   |
    -------------------------------------------------------------------'


If the swap status region indicates that the images are not contiguous,
bootutil completes the swap operation that was in progress when the system was
reset.  In other words, it applies the procedure defined in the previous
section, moving image 1 into slot 0 and image 0 into slot 1.  If the boot
status file indicates that an image part is present in the scratch area, this
part is copied into the correct location by starting at step e or step h in the
area-swap procedure, depending on whether the part belongs to image 0 or image
1.

After the swap operation has been completed, the boot loader proceeds as though
it had just been started.

*** INTEGRITY CHECK

An image is checked for integrity immediately before it gets copied into the
primary slot.  If the boot loader doesn't perform an image swap, then it can
perform an optional integrity check of the image in slot0 if
MCUBOOT_VALIDATE_SLOT0 is set, otherwise it doesn't perform an integrity check.

During the integrity check, the boot loader verifies the following aspects of
an image:
    * 32-bit magic number must be correct (0x96f3b83c).
    * Image must contain a SHA256 TLV.
    * Calculated SHA256 must match SHA256 TLV contents.
    * Image *may* contain a signature TLV.  If it does, its contents must be
      verifiable using a key embedded in the boot loader.

*** SECURITY

As indicated above, the final step of the integrity check is signature
verification.  The boot loader can have one or more public keys embedded in it
at build time.  During signature verification, the boot loader verifies that an
image was signed with a private key that corresponds to one of its public keys.
The image signature TLV indicates the index of the key that is has been signed
with.  The boot loader uses this index to identify the corresponding public
key.

For information on embedding public keys in the boot loader, as well as
producing signed images, see: doc/signed_images.md