You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/12/14 01:17:53 UTC
[1/4] incubator-mynewt-site git commit: Updated bootloader doc
Repository: incubator-mynewt-site
Updated Branches:
refs/heads/asf-site f78bd4195 -> 6e429bad9
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6e429bad/latest/os/modules/bootloader/bootloader/index.html
----------------------------------------------------------------------
diff --git a/latest/os/modules/bootloader/bootloader/index.html b/latest/os/modules/bootloader/bootloader/index.html
index c8d2b3f..4ebc284 100644
--- a/latest/os/modules/bootloader/bootloader/index.html
+++ b/latest/os/modules/bootloader/bootloader/index.html
@@ -527,21 +527,26 @@
</div>
<h1 id="bootloader">Bootloader</h1>
-<p>The "bootloader" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:</p>
+<p>The "bootloader" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process.</p>
+<p>The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:</p>
<ul>
<li>Calculates hash of the image.</li>
<li>Uses public key to uncover hash value from included signature. </li>
<li>Compares the calculated and uncovered hashes for a match.</li>
</ul>
<p>The "secure bootloader" should be placed in protected memory on a given microcontroller.</p>
-<p>The Mynewt code is structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an
+<p>The Mynewt bootloader comprises two packages:</p>
+<ul>
+<li>The bootutil library (boot/bootutil)</li>
+<li>The boot application (apps/boot)</li>
+</ul>
+<p>The Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an
architecture-specific project. Boot loader functionality is separated in this
manner for the following two reasons:</p>
<ol>
<li>By keeping architecture-dependent code separate, the bootutil library can be
reused among several boot loaders.</li>
-<li>By excluding the last boot step from the library, the rest of the code can
- be tested in a sim environment.</li>
+<li>By excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.</li>
</ol>
<h3 id="limitations">Limitations</h3>
<p>The boot loader currently only supports images with the following
@@ -568,7 +573,15 @@ characteristics:</p>
<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">ih_tlv_size</span>; <span style="color: #177500">/* Trailing TLVs */</span>
<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">ih_key_id</span>;
<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">_pad1</span>;
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">ih_hdr_size</span>;
+ <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">ih_hdr_s<</span> <span style="color: #000000">bok@bok</span>.<span style="color: #000000">net</span>
+<span style="color: #1C01CE">35</span><span style="color: #000000">d33</span>
+<span style="color: #000000"><</span> <span style="color: #000000">ericmanganaro@gmail</span>.<span style="color: #000000">com</span>
+<span style="color: #1C01CE">42</span><span style="color: #000000">d39</span>
+<span style="color: #000000"><</span> <span style="color: #000000">tam@proxy</span>.<span style="color: #000000">co</span>
+<span style="color: #1C01CE">55</span><span style="color: #000000">d51</span>
+<span style="color: #000000"><</span> <span style="color: #000000">nathan@natb1</span>.<span style="color: #000000">com</span>
+<span style="color: #1C01CE">110</span><span style="color: #000000">d105</span>
+<span style="color: #000000"><</span> <span style="color: #000000">rvs@apache</span>.<span style="color: #000000">orgize</span>;
<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">_pad2</span>;
<span style="color: #A90D91">uint32_t</span> <span style="color: #000000">ih_img_size</span>; <span style="color: #177500">/* Does not include header. */</span>
<span style="color: #A90D91">uint32_t</span> <span style="color: #000000">ih_flags</span>;
@@ -591,8 +604,16 @@ case of changes to the format of the image header.</p>
</pre></div>
-<p>Security data gets added as a footer at the end of the image.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/*</span>
+<p>Optional type-length-value records (TLVs) containing image metadata are placed
+after the end of the image. For example, security data gets added as a footer at the end of the image.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/** Image trailer TLV format. All fields in little endian. */</span>
+<span style="color: #A90D91">struct</span> <span style="color: #000000">image_tlv</span> {
+ <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">it_type</span>; <span style="color: #177500">/* IMAGE_TLV_[...]. */</span>
+ <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">_pad</span>;
+ <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">it_len</span> <span style="color: #177500">/* Data length (not including TLV header). */</span>
+};
+
+<span style="color: #177500">/*</span>
<span style="color: #177500"> * Image trailer TLV types.</span>
<span style="color: #177500"> */</span>
<span style="color: #633820">#define IMAGE_TLV_SHA256 1 </span><span style="color: #177500">/* SHA256 of image hdr and body */</span><span style="color: #633820"></span>
@@ -601,13 +622,23 @@ case of changes to the format of the image header.</p>
</pre></div>
-<h3 id="flash-areas">Flash Areas</h3>
-<p>Bootutil uses the same concept of "flash areas" as the nffs file system.
-Briefly, an 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.</p>
-<p>The areas used for image data must not be used for anything else. In
-particular, these areas must be kept separate from the nffs file system.</p>
+<h3 id="flash-map">Flash Map</h3>
+<p>A Mynewt device's flash is partitioned according to its <em>flash map</em>. At a high
+level, the flash map maps numeric IDs to <em>flash areas</em>. A flash area is a
+region of disk with the following properties:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">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.
+</pre></div>
+
+
+<p>The boot loader uses the following flash areas:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#define FLASH_AREA_BOOTLOADER 0</span>
+<span style="color: #633820">#define FLASH_AREA_IMAGE_0 1</span>
+<span style="color: #633820">#define FLASH_AREA_IMAGE_1 2</span>
+<span style="color: #633820">#define FLASH_AREA_IMAGE_SCRATCH 3</span>
+</pre></div>
+
+
<h3 id="image-slots">Image Slots</h3>
<p>A portion of the flash memory is partitioned into two image slots: a primary
slot and a secondary slot. The boot loader will only run an image from the
@@ -616,65 +647,398 @@ 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.</p>
<p>In addition to the two image slots, the boot loader requires a scratch area to
allow for reliable image swapping.</p>
-<p>All areas used by image data (including the scratch area) must be the same
-size.</p>
+<h3 id="boot-states">Boot States</h3>
+<p>Logically, you can think of a pair of flags associated with each image slot:
+pending and confirmed. On startup, the boot loader determines the state of the
+device by inspecting each pair of flags. These flags have the following
+meanings:</p>
+<ul>
+<li>pending: image gets tested on next reboot; absent subsequent confirm command,
+ revert to original image on second reboot.</li>
+<li>confirmed: always use image unless excluded by a test image.</li>
+</ul>
+<p>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. This is 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.</p>
+<p>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.</p>
+<p>The following set of tables illustrate the three possible states that the
+device can be in:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> | slot-0 | slot-1 |
+---------------+--------+--------|
+ pending | | |
+ confirmed | X | |
+---------------+--------+--------'
+Image 0 confirmed; |
+No change on reboot |
+---------------------------------'
+
+ | slot-0 | slot-1 |
+---------------+--------+--------|
+ pending | | X |
+ confirmed | X | |
+---------------+--------+--------'
+Image 0 confirmed; |
+Test image 1 on next reboot |
+---------------------------------'
+
+ | slot-0 | slot-1 |
+---------------+--------+--------|
+ pending | | |
+ confirmed | | X |
+---------------+--------+--------'
+Testing image 0; |
+Revert to image 1 on next reboot |
+---------------------------------'
+</pre></div>
+
+
<h3 id="boot-vector">Boot Vector</h3>
-<p>If a vector file contains a version which doesn't correspond to an image
-actually present in flash, the boot loader deletes the file and procedes as
-though the file was not present.</p>
-<h3 id="boot-status">Boot Status</h3>
-<p>The boot status record allows the boot loader to recover in case it was reset
-while in the middle of an image swap operation. Image swapping is discussed
-later in this document. </p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">boot_status_table</span> {
- <span style="color: #177500">/**</span>
-<span style="color: #177500"> * For each field, a value of 0 means "any".</span>
-<span style="color: #177500"> */</span>
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_magic_slot0</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_magic_scratch</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_copy_done_slot0</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_status_source</span>;
-};
+<p>At startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two
+records (called "image trailers"), one written at the end of each image slot.
+An image trailer has the following structure:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> 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
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~ MAGIC (16 octets) ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~ ~
+~ Swap status (128 * min-write-size * 3) ~
+~ ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Copy done | 0xff padding (up to min-write-sz - 1) ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Image OK | 0xff padding (up to min-write-sz - 1) ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</pre></div>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">boot_status</span> {
- <span style="color: #A90D91">uint32_t</span> <span style="color: #000000">idx</span>; <span style="color: #177500">/* Which area we're operating on */</span>
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">state</span>; <span style="color: #177500">/* Which part of the swapping process are we at */</span>
-};
+<p>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.</p>
+<p>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.</p>
+<p>The fields are defined as follows:</p>
+<ol>
+<li>
+<p>MAGIC: The following 16 bytes, written in host-byte-order:</p>
+<p>const uint32_t boot_img_magic[4] = {
+ 0xf395c277,
+ 0x7fefd260,
+ 0x0f505235,
+ 0x8079b62c,
+};</p>
+</li>
+<li>
+<p>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.</p>
+</li>
+<li>
+<p>Copy done: A single byte indicating whether the image in this slot is
+complete (0x01=d< bok@bok.net
+35d33
+< ericmanganaro@gmail.com
+42d39
+< tam@proxy.co
+55d51
+< nathan@natb1.com
+110d105
+< rvs@apache.orgone; 0xff=not done).</p>
+</li>
+<li>
+<p>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).</p>
+</li>
+</ol>
+<p>The boot vector 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
+boot vector. It is better to map all the possible vector states to the swap types (None, Test, Revert)
+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 boot vector.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">State I
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Unset | Unset |
+ image-ok | Any | N/A |
+-----------------+--------+--------'
+ pending | | |
+ confirmed | X | |
+-----------------+--------+--------'
+ swap: none |
+-----------------------------------'
+
+
+State II
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Any | Good |
+ image-ok | Any | N/A |
+-----------------+--------+--------'
+ pending | | X |
+ confirmed | X | |
+-----------------+--------+--------'
+ swap: test |
+-----------------------------------'
+
+
+State III
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Good | Unset |
+ image-ok | 0xff | N/A |
+-----------------+--------+--------'
+ pending | | |
+ confirmed | | X |
+-----------------+--------+--------'
+ swap: revert (test image running) |
+-----------------------------------'
+
+
+State IV
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Good | Unset |
+ image-ok | 0x01 | N/A |
+-----------------+--------+--------'
+ pending | | |
+ confirmed | X | |
+-----------------+--------+--------'
+ swap: none (confirmed test image) |
+-----------------------------------'
</pre></div>
+<h3 id="high-level-operation">High-level Operation</h3>
+<p>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.</p>
+<p>Procedure:</p>
+<p>A. Inspect swap status region; is an interrupted swap is being resumed?
+ Yes: Complete the partial swap operation; skip to step C.
+ No: Proceed to step B.</p>
+<p>B. Insect boot vector; 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 boot vector.
+ c. Proceed to step C.
+ No.
+ a. Erase invalid image.
+ b. Persist failure of swap procedure to boot vector.
+ c. Proceed to step C.
+ No: Proceed to step C.</p>
+<p>C. Boot into image in slot 0.</p>
<h3 id="image-swapping">Image Swapping</h3>
+<p>The boot loader swaps the contents of the two image slots for two reasons:
+ * User has issued an "image test" operation; the image in slot-1 should be
+ run once (state II).
+ * Test image rebooted without being confirmed; the boot loader should
+ revert to the original image currently in slot-1 (state III).</p>
<p>If the boot vector 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 process. The two images are swapped according to
-the following procedure:</p>
-<h3 id="verifying-integrity-of-image">Verifying integrity of image</h3>
+resets in the middle of the swap operation. The two images are swapped
+according to the following procedure:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">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.
+ 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].
+ j. Write updated swap status (iii).
+
+3. Persist completion of swap procedure to slot 0 image trailer.
+</pre></div>
+
+
+<p>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).</p>
+<p>The particulars of step 3 vary depending on whether an image is being tested or
+reverted:
+ * test:
+ o Write slot0.copy_done = 1
+ (should now be in state III)</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">* revert:
+ o Write slot0.magic = BOOT_MAGIC
+ o Write slot0.copy_done = 1
+ o Write slot0.image_ok = 1
+ (should now be in state IV)
+</pre></div>
+
+
+<h3 id="swap-status">Swap Status</h3>
+<p>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.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> 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 |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+</pre></div>
+
+
+<p>And now, in English...</p>
+<p>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.</p>
+<p>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)</p>
+<p>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.</p>
+<p>Each sector-state pair is represented as a set of three records. The record
+values map to the above four states as follows</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> | rec0 | rec1 | rec2
+--------+------+------+------
+state 0 | 0xff | 0xff | 0xff
+state 1 | 0x01 | 0xff | 0xff
+state 2 | 0x01 | 0x02 | 0xff
+state 3 | 0x01 | 0x02 | 0x03
+</pre></div>
+
+
+<p>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.</p>
<h3 id="reset-recovery">Reset Recovery</h3>
<p>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
-boot status file to determine how the image parts are placed in flash.</p>
-<p>If the boot status file 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
+boot vector to determine how the image parts are distributed in flash.</p>
+<p>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 boot vector
+contents to swap status location. In these tables, the "source" field
+indicates where the swap status region is located.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> | 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: varies |
+------------------------------------+------------------------------+
+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. |
+-------------------------------------------------------------------'
+</pre></div>
+
+
+<p>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.</p>
<p>After the swap operation has been completed, the boot loader proceeds as though
it had just been started.</p>
-<h3 id="api">API</h3>
-<h3 id="example">Example</h3>
-<h3 id="dependencies">Dependencies</h3>
-<p>The bootloader depends on the following OS kernel functions:</p>
-<p>The bootloader does not depend on any flash file system.</p>
-<h3 id="list-of-functions">List of Functions</h3>
-<p><Comments such as these instructions are placed within angle brackets. List all the functions here. Note how the anchors work. You put the text you want to show up as a link within [] and the relevant #heading within (). Note that the header has to have at least 2 words for the anchor to work - that's how it is. "no-highlight" disables syntax highlighting. You can enable it for a particular language by specifying what the language is instead of "no-highlight". Be warned that this highlighting or no-highlighting specification may not show up nicely on Mou.></p>
-<p>The functions available in bootloader are:</p>
+<h3 id="integrity-check">Integrity Check</h3>
+<p>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
+doesn't perform an integrity check.</p>
+<p>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 matche SHA256 TLV contents.
+ * Image <em>may</em> contain a signature TLV. If it does, its contents must be
+ verifiable using a key embedded in the boot loader.</p>
+<h3 id="image-signing-and-verification">Image Signing and Verification</h3>
+<p>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.</p>
+<p>For information on embedding public keys in the boot loader, as well as
+producing signed images, see: boot/bootutil/signed_images.md </p>
<div class="row">
[2/4] incubator-mynewt-site git commit: Updated bootloader doc
Posted by ad...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6e429bad/latest/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/latest/mkdocs/search_index.json b/latest/mkdocs/search_index.json
index 9cada04..22b3186 100644
--- a/latest/mkdocs/search_index.json
+++ b/latest/mkdocs/search_index.json
@@ -5142,12 +5142,12 @@
},
{
"location": "/os/modules/bootloader/bootloader/",
- "text": "Bootloader\n\n\nThe \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:\n\n\n\n\nCalculates hash of the image.\n\n\nUses public key to uncover hash value from included signature. \n\n\nCompares the calculated and uncovered hashes for a match.\n\n\n\n\nThe \"secure bootloader\" should be placed in protected memory on a given microcontroller.\n\n\nThe Mynewt code is structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot load
er functionality is separated in this\nmanner for the following two reasons:\n\n\n\n\nBy keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders.\n\n\nBy excluding the last boot step from the library, the rest of the code can\n be tested in a sim environment.\n\n\n\n\nLimitations\n\n\nThe boot loader currently only supports images with the following\ncharacteristics:\n\n\n\n\nBuilt to run from flash.\n\n\nBuild to run from a fixed location (i.e., position-independent).\n\n\n\n\nImage Format\n\n\nThe following definitions describe the image header format.\n\n\n#define IMAGE_MAGIC 0x96f3b83c\n\n\n#define IMAGE_MAGIC_NONE 0xffffffff\n\n\n\nstruct\n \nimage_version\n {\n \nuint8_t\n \niv_major\n;\n \nuint8_t\n \niv_minor\n;\n \nuint16_t\n \niv_revision\n;\n \nuint32_t\n \niv_build_num\n;\n};\n\n\n/** Image header. All fields are in little endian byte order. */\n\n\nstruct\n \nimage_header\n
{\n \nuint32_t\n \nih_magic\n;\n \nuint16_t\n \nih_tlv_size\n; \n/* Trailing TLVs */\n\n \nuint8_t\n \nih_key_id\n;\n \nuint8_t\n \n_pad1\n;\n \nuint16_t\n \nih_hdr_size\n;\n \nuint16_t\n \n_pad2\n;\n \nuint32_t\n \nih_img_size\n; \n/* Does not include header. */\n\n \nuint32_t\n \nih_flags\n;\n \nstruct\n \nimage_version\n \nih_ver\n;\n \nuint32_t\n \n_pad3\n;\n};\n\n\n\n\n\nThe \nih_hdr_size\n field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header.\n\n\nThe following are the image header flags available.\n\n\n#define IMAGE_F_PIC 0x00000001\n\n\n#define IMAGE_F_SHA256 0x00000002 \n/* Image contains hash TLV */\n\n\n#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 \n/* PKCS15 w/RSA and SHA */\n\n\n#define IMAGE_F_ECDSA224_SHA256 0x00000008 \n/* ECDSA256 over SHA256 */\n\n\n
#define IMAGE_F_NON_BOOTABLE 0x00000010\n\n\n#define IMAGE_HEADER_SIZE 32\n\n\n\n\n\n\nSecurity data gets added as a footer at the end of the image.\n\n\n/*\n\n\n * Image trailer TLV types.\n\n\n */\n\n\n#define IMAGE_TLV_SHA256 1 \n/* SHA256 of image hdr and body */\n\n\n#define IMAGE_TLV_RSA2048 2 \n/* RSA2048 of hash output */\n\n\n#define IMAGE_TLV_ECDSA224 3 \n/* ECDSA of hash output */\n\n\n\n\n\n\nFlash Areas\n\n\nBootutil uses the same concept of \"flash areas\" as the nffs file system.\nBriefly, an area is a region of disk with the following properties:\n1. An area can be fully erased without affecting any other areas.\n2. A write to one area does not restrict writes to other areas.\n\n\nThe areas used for image data must not be used for anything else. In\nparticular, these areas must be kept separate from the nffs file system.\n\n\nImage Slots\n\n\nA portion of the flash memory is partitioned into two image slots: a p
rimary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary slot, it must swap the two images in flash prior to booting.\n\n\nIn addition to the two image slots, the boot loader requires a scratch area to\nallow for reliable image swapping.\n\n\nAll areas used by image data (including the scratch area) must be the same\nsize.\n\n\nBoot Vector\n\n\nIf a vector file contains a version which doesn't correspond to an image\nactually present in flash, the boot loader deletes the file and procedes as\nthough the file was not present.\n\n\nBoot Status\n\n\nThe boot status record allows the boot loader to recover in case it was reset\nwhile in the middle of an image swap operation. Image swapping is discussed\nlater in this document. \n\n\nstruct\n \nboot_status_table\n {\n \n/**\n\n\n * For ea
ch field, a value of 0 means \nany\n.\n\n\n */\n\n \nuint8_t\n \nbst_magic_slot0\n;\n \nuint8_t\n \nbst_magic_scratch\n;\n \nuint8_t\n \nbst_copy_done_slot0\n;\n \nuint8_t\n \nbst_status_source\n;\n};\n\n\n\n\n\nstruct\n \nboot_status\n {\n \nuint32_t\n \nidx\n; \n/* Which area we\nre operating on */\n\n \nuint8_t\n \nstate\n; \n/* Which part of the swapping process are we at */\n\n};\n\n\n\n\n\nImage Swapping\n\n\nIf the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the process. The two images are swapped according to\nthe following procedure:\n\n\nVerifying integrity of image\n\n\nReset Recovery\n\n\nIf the boot loader resets in the middle of a swap operation, the two
images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot status file to determine how the image parts are placed in flash.\n\n\nIf the boot status file indicates that the images are not contiguous, bootutil\ncompletes the swap operation that was in progress when the system was reset.\nIn other words, it applies the procedure defined in the previous section,\nmoving image 1 into slot 0 and image 0 into slot 1. If the boot status file\nindicates that an image part is present in the scratch area, this part is\ncopied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1.\n\n\nAfter the swap operation has been completed, the boot loader proceeds as though\nit had just been started.\n\n\nAPI\n\n\nExample\n\n\nDependencies\n\n\nThe bootloader depends on the following OS kernel functions:\n\n\nThe bootloader does not depend on any flash file system.\n\n\nLi
st of Functions\n\n\n\n\nThe functions available in bootloader are:",
+ "text": "Bootloader\n\n\nThe \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process.\n\n\nThe bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:\n\n\n\n\nCalculates hash of the image.\n\n\nUses public key to uncover hash value from included signature. \n\n\nCompares the calculated and uncovered hashes for a match
.\n\n\n\n\nThe \"secure bootloader\" should be placed in protected memory on a given microcontroller.\n\n\nThe Mynewt bootloader comprises two packages:\n\n\n\n\nThe bootutil library (boot/bootutil)\n\n\nThe boot application (apps/boot)\n\n\n\n\nThe Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nmanner for the following two reasons:\n\n\n\n\nBy keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders.\n\n\nBy excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.\n\n\n\n\nLimitations\n\n\nThe boot loader currently only supports images with the following\ncha
racteristics:\n\n\n\n\nBuilt to run from flash.\n\n\nBuild to run from a fixed location (i.e., position-independent).\n\n\n\n\nImage Format\n\n\nThe following definitions describe the image header format.\n\n\n#define IMAGE_MAGIC 0x96f3b83c\n\n\n#define IMAGE_MAGIC_NONE 0xffffffff\n\n\n\nstruct\n \nimage_version\n {\n \nuint8_t\n \niv_major\n;\n \nuint8_t\n \niv_minor\n;\n \nuint16_t\n \niv_revision\n;\n \nuint32_t\n \niv_build_num\n;\n};\n\n\n/** Image header. All fields are in little endian byte order. */\n\n\nstruct\n \nimage_header\n {\n \nuint32_t\n \nih_magic\n;\n \nuint16_t\n \nih_tlv_size\n; \n/* Trailing TLVs */\n\n \nuint8_t\n \nih_key_id\n;\n \nuint8_t\n \n_pad1\n;\n \nuint16_t\n \nih_hdr_s\n \nbok@bok\n.\nnet\n\n\n35\nd33\n\n\n \nericmanganaro@gmail\n.\ncom\n\n\n42\nd39\n\n\n \ntam@proxy\n.\nco\n\n\n55\nd51\n\n\n \nnathan@natb1\n.\ncom\n\n\n110\nd105\n\n\n \nrvs@apache\n.\norgize\n;\n \nuint16_t\n \n_pad2\n;\n
\nuint32_t\n \nih_img_size\n; \n/* Does not include header. */\n\n \nuint32_t\n \nih_flags\n;\n \nstruct\n \nimage_version\n \nih_ver\n;\n \nuint32_t\n \n_pad3\n;\n};\n\n\n\n\n\nThe \nih_hdr_size\n field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header.\n\n\nThe following are the image header flags available.\n\n\n#define IMAGE_F_PIC 0x00000001\n\n\n#define IMAGE_F_SHA256 0x00000002 \n/* Image contains hash TLV */\n\n\n#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 \n/* PKCS15 w/RSA and SHA */\n\n\n#define IMAGE_F_ECDSA224_SHA256 0x00000008 \n/* ECDSA256 over SHA256 */\n\n\n#define IMAGE_F_NON_BOOTABLE 0x00000010\n\n\n#define IMAGE_HEADER_SIZE 32\n\n\n\n\n\n\nOptional type-length-value records (TLVs) containing image metadata are placed\nafter the end of the image. For examp
le, security data gets added as a footer at the end of the image.\n\n\n/** Image trailer TLV format. All fields in little endian. */\n\n\nstruct\n \nimage_tlv\n {\n \nuint8_t\n \nit_type\n; \n/* IMAGE_TLV_[...]. */\n\n \nuint8_t\n \n_pad\n;\n \nuint16_t\n \nit_len\n \n/* Data length (not including TLV header). */\n\n};\n\n\n/*\n\n\n * Image trailer TLV types.\n\n\n */\n\n\n#define IMAGE_TLV_SHA256 1 \n/* SHA256 of image hdr and body */\n\n\n#define IMAGE_TLV_RSA2048 2 \n/* RSA2048 of hash output */\n\n\n#define IMAGE_TLV_ECDSA224 3 \n/* ECDSA of hash output */\n\n\n\n\n\n\nFlash Map\n\n\nA Mynewt device's flash is partitioned according to its \nflash map\n. At a high\nlevel, the flash map maps numeric IDs to \nflash areas\n. A flash area is a\nregion of disk with the following properties:\n\n\n1. An area can be fully erased without affecting any other areas.\n2. A write to one area does not restrict writes to other areas.\n\n\n\
n\n\nThe boot loader uses the following flash areas:\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n\n\n\n\nImage Slots\n\n\nA portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary slot, it must swap the two images in flash prior to booting.\n\n\nIn addition to the two image slots, the boot loader requires a scratch area to\nallow for reliable image swapping.\n\n\nBoot States\n\n\nLogically, you can think of a pair of flags associated with each image slot:\npending and confirmed. On startup, the boot loader determines the state of the\ndevice
by inspecting each pair of flags. These flags have the following\nmeanings:\n\n\n\n\npending: image gets tested on next reboot; absent subsequent confirm command,\n revert to original image on second reboot.\n\n\nconfirmed: always use image unless excluded by a test image.\n\n\n\n\nIn English, when the user wants to run the secondary image, they set the\npending flag for the second slot and reboot the device. On startup, the boot\nloader will swap the two images in flash, clear the secondary slot's pending\nflag, and run the newly-copied image in slot 0. This is a temporary state; if\nthe device reboots again, the boot loader swaps the images back to their\noriginal slots and boots into the original image. If the user doesn't want to\nrevert to the original state, they can make the current state permanent by\nsetting the confirmed flag in slot 0.\n\n\nSwitching to an alternate image is a two-step process (set + confirm) to\nprevent a device from becoming \"bricked\" b
y bad firmware. If the device\ncrashes immediately upon booting the second image, the boot loader reverts to\nthe working image, rather than repeatedly rebooting into the bad image.\n\n\nThe following set of tables illustrate the three possible states that the\ndevice can be in:\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | X | |\n---------------+--------+--------\n\nImage 0 confirmed; |\nNo change on reboot |\n---------------------------------\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | X |\n confirmed | X | |\n---------------+--------+--------\n\nImage 0 confirmed; |\nTest image 1 on next reboot |\n---------------------------------\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed |
| X |\n---------------+--------+--------\n\nTesting image 0; |\nRevert to image 1 on next reboot |\n---------------------------------\n\n\n\n\n\n\nBoot Vector\n\n\nAt startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two\nrecords (called \"image trailers\"), one written at the end of each image slot.\nAn image trailer has the following structure:\n\n\n 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ MAGIC (16 octets) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ ~\n~ Swap status (128 * min-write-size * 3) ~\n~
~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Copy done | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Image OK | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n\n\n\n\n\nThese records are at the end of each image slot. The offset immediately\nfollowing such a record represents the start of the next flash area.\n\n\nNote: \"min-write-size\" is a property of the flash hardware. If the hardware\nallows individual bytes to be written at arbitrary addresses, then\nmin-write-size is 1. If the hardware only allows writes at even addresses,\nthen min-write-size is 2, and so on.\n\n\nThe fields are defined as follows:\n\n\n\n\n\n\nMAGIC: The following 16 bytes, written in host-byte-order:\n\n\nconst uint32_t boot_img_magic[4] = {\n 0xf395c277,\n 0x7fefd260,\n 0x0f505235,\n 0x8079b62c,\n};\n\n
\n\n\n\n\nSwap status: A series of single-byte records. Each record corresponds to a\nflash sector in an image slot. A swap status byte indicate the location of\nthe corresponding sector data. During an image swap, image data is moved one\nsector at a time. The swap status is necessary for resuming a swap operation\nif the device rebooted before a swap operation completed.\n\n\n\n\n\n\nCopy done: A single byte indicating whether the image in this slot is\ncomplete (0x01=d\n bok@bok.net\n35d33\n\n ericmanganaro@gmail.com\n42d39\n\n tam@proxy.co\n55d51\n\n nathan@natb1.com\n110d105\n\n rvs@apache.orgone; 0xff=not done).\n\n\n\n\n\n\nImage OK: A single byte indicating whether the image in this slot has been\nconfirmed as good by the user (0x01=confirmed; 0xff=not confirmed).\n\n\n\n\n\n\nThe boot vector records are structured around the limitations imposed by flash\nhardware. As a consequence, they do not have a very intuitive design, and it\nis difficult to get a sense of the sta
te of the device just by looking at the\nboot vector. It is better to map all the possible vector states to the swap types (None, Test, Revert)\nvia a set of tables. These tables are reproduced below.\nIn these tables, the \"pending\" and \"confirmed\" flags are shown for illustrative\npurposes; they are not actually present in the boot vector.\n\n\nState I\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Unset | Unset |\n image-ok | Any | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: none |\n-----------------------------------\n\n\n\nState II\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Any | Good |\n image-ok | Any | N/A |\n-----------------+--------+--------\n\n pending | | X |\n co
nfirmed | X | |\n-----------------+--------+--------\n\n swap: test |\n-----------------------------------\n\n\n\nState III\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0xff | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | | X |\n-----------------+--------+--------\n\n swap: revert (test image running) |\n-----------------------------------\n\n\n\nState IV\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0x01 | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: none (confirmed test image) |\n-----------------------------------\n\n\n\n\n\n\nHigh-level Operation\n\n\nWith the terms defin
ed, we can now explore the boot loader's operation. First,\na high-level overview of the boot process is presented. Then, the following\nsections describe each step of the process in more detail.\n\n\nProcedure:\n\n\nA. Inspect swap status region; is an interrupted swap is being resumed?\n Yes: Complete the partial swap operation; skip to step C.\n No: Proceed to step B.\n\n\nB. Insect boot vector; is a swap requested?\n Yes.\n 1. Is the requested image valid (integrity and security check)?\n Yes.\n a. Perform swap operation.\n b. Persist completion of swap procedure to boot vector.\n c. Proceed to step C.\n No.\n a. Erase invalid image.\n b. Persist failure of swap procedure to boot vector.\n c. Proceed to step C.\n No: Proceed to step C.\n\n\nC. Boot into image in slot 0.\n\n\nImage Swapping\n\n\nThe boot loader swaps the contents of the two image sl
ots for two reasons:\n * User has issued an \"image test\" operation; the image in slot-1 should be\n run once (state II).\n * Test image rebooted without being confirmed; the boot loader should\n revert to the original image currently in slot-1 (state III).\n\n\nIf the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the swap operation. The two images are swapped\naccording to the following procedure:\n\n\n1. Determine how many flash sectors each image slot consists of. This\n number must be the same for both slots.\n2. Iterate the list of sector indices in descending order (i.e., starting\n with the greatest index); current element = \nindex\n.\n b. Erase scratch area.\n c. Cop
y slot0[index] to scratch area.\n d. Write updated swap status (i).\n\n e. Erase slot1[index]\n f. Copy slot0[index] to slot1[index]\n - If these are the last sectors (i.e., first swap being perfomed),\n copy the full sector *except* the image trailer.\n - Else, copy entire sector contents.\n g. Write updated swap status (ii).\n\n h. Erase slot0[index].\n i. Copy scratch area slot0[index].\n j. Write updated swap status (iii).\n\n3. Persist completion of swap procedure to slot 0 image trailer.\n\n\n\n\n\nThe additional caveats in step 2f are necessary so that the slot 1 image trailer\ncan be written by the user at a later time. With the image trailer unwritten,\nthe user can test the image in slot 1 (i.e., transition to state II).\n\n\nThe particulars of step 3 vary depending on whether an image is being tested or\nreverted:\n * test:\n o Write slot0.copy_done = 1\n (should now be in state III)\n\n\n* revert:\n o Write
slot0.magic = BOOT_MAGIC\n o Write slot0.copy_done = 1\n o Write slot0.image_ok = 1\n (should now be in state IV)\n\n\n\n\n\nSwap Status\n\n\nThe swap status region allows the boot loader to recover in case it restarts in\nthe middle of an image swap operation. The swap status region consists of a\nseries of single-byte records. These records are written independently, and\ntherefore must be padded according to the minimum write size imposed by the\nflash hardware. In the below figure, a min-write-size of 1 is assumed for\nsimplicity. The structure of the swap status region is illustrated below. In\nthis figure, a min-write-size of 1 is assumed for simplicity.\n\n\n 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
+-+-+-+-+-+-+-+-+-+-+\n|sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec125,state 2 | |\n+-+-+-+-+-+-+-+-+ +\n~ ~\n~ [Records for indices 124 through 1 ~\n~ ~\n~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n\n\n\n\n\nAnd now, in English...\n\n\nEach image slot is partitioned into a sequence of flash sectors. If we were to\nenumerate the sectors in a single slot, starting at 0, we would have a list of\nsector indices. Since there are two image slots, each sector index would\ncorrespond to a pair of sector
s. For example, sector index 0 corresponds to\nthe first sector in slot 0 and the first sector in slot 1. Furthermore, we\nimpose a limit of 128 indices. If an image slot consists of more than 128\nsectors, the flash layout is not compatible with this boot loader. Finally,\nreverse the list of indices such that the list starts with index 127 and ends\nwith 0. The swap status region is a representation of this reversed list.\n\n\nDuring a swap operation, each sector index transitions through four separate\nstates:\n 0. slot 0: image 0, slot 1: image 1, scratch: N/A\n 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1-\ns, erase 1)\n 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0-\n1, erase 0)\n 3. slot 0: image 1, slot 1: image 0, scratch: N/A (s-\n0)\n\n\nEach time a sector index transitions to a new state, the boot loader writes a\nrecord to the swap status region. Logically, the boot loader only needs one\nrecord per sector ind
ex to keep track of the current swap state. However, due\nto limitations imposed by flash hardware, a record cannot be overwritten when\nan index's state changes. To solve this problem, the boot loader uses three\nrecords per sector index rather than just one.\n\n\nEach sector-state pair is represented as a set of three records. The record\nvalues map to the above four states as follows\n\n\n | rec0 | rec1 | rec2\n--------+------+------+------\nstate 0 | 0xff | 0xff | 0xff\nstate 1 | 0x01 | 0xff | 0xff\nstate 2 | 0x01 | 0x02 | 0xff\nstate 3 | 0x01 | 0x02 | 0x03\n\n\n\n\n\nThe swap status region can accommodate 128 sector indices. Hence, the size of\nthe region, in bytes, is 128 * min-write-size * 3. The number 128 is chosen\nsomewhat arbitrarily and will likely be made configurable. The only\nrequirement for the index count is that is is great enough to account for a\nmaximum-sized image (i.e., at least as great as the total sector count in an\nimage slot). If a device
's image slots use less than 128 sectors, the first\nrecord that gets written will be somewhere in the middle of the region. For\nexample, if a slot uses 64 sectors, the first sector index that gets swapped is\n63, which corresponds to the exact halfway point within the region.\n\n\nReset Recovery\n\n\nIf the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot vector to determine how the image parts are distributed in flash.\n\n\nThe first step is determine where the relevant swap status region is located.\nBecause this region is embedded within the image slots, its location in flash\nchanges during a swap operation. The below set of tables map boot vector\ncontents to swap status location. In these tables, the \"source\" field\nindicates where the swap status region is located.\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Go
od | Any |\ncopy-done | 0x01 | N/A |\n----------+------------+------------\n\nsource: none |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------\n\nsource: slot 0 |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Any | Good |\ncopy-done | Any | N/A |\n----------+------------+------------\n\nsource: scratch |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Unset | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------|\nsource: varies |\n------------------------
------------+------------------------------+\nThis represents one of two cases: |\no No swaps ever (no status to read, so no harm in checking). |\no Mid-revert; status in slot 0. |\n-------------------------------------------------------------------\n\n\n\n\n\n\nIf the swap status region indicates that the images are not contiguous,\nbootutil completes the swap operation that was in progress when the system was\nreset. In other words, it applies the procedure defined in the previous\nsection, moving image 1 into slot 0 and image 0 into slot 1. If the boot\nstatus file indicates that an image part is present in the scratch area, this\npart is copied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1.\n\n\nAfter the swap operation has been completed, the boot loader proceeds as though\nit had just been started.\n\n
\nIntegrity Check\n\n\nAn image is checked for integrity immediately before it gets copied into the\nprimary slot. If the boot loader doesn't perform an image swap, then it\ndoesn't perform an integrity check.\n\n\nDuring the integrity check, the boot loader verifies the following aspects of\nan image:\n * 32-bit magic number must be correct (0x96f3b83c).\n * Image must contain a SHA256 TLV.\n * Calculated SHA256 must matche SHA256 TLV contents.\n * Image \nmay\n contain a signature TLV. If it does, its contents must be\n verifiable using a key embedded in the boot loader.\n\n\nImage Signing and Verification\n\n\nAs indicated above, the final step of the integrity check is signature\nverification. The boot loader can have one or more public keys embedded in it\nat build time. During signature verification, the boot loader verifies that an\nimage was signed with a private key that corresponds to one of its public keys.\nThe image signature TLV indicates the index
of the key that is has been signed\nwith. The boot loader uses this index to identify the corresponding public\nkey.\n\n\nFor information on embedding public keys in the boot loader, as well as\nproducing signed images, see: boot/bootutil/signed_images.md",
"title": "toc"
},
{
"location": "/os/modules/bootloader/bootloader/#bootloader",
- "text": "The \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it: Calculates hash of the image. Uses public key to uncover hash value from included signature. Compares the calculated and uncovered hashes for a match. The \"secure bootloader\" should be placed in protected memory on a given microcontroller. The Mynewt code is structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nman
ner for the following two reasons: By keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders. By excluding the last boot step from the library, the rest of the code can\n be tested in a sim environment.",
+ "text": "The \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it: Calculates hash of the image. Uses public key to uncover hash value from included signature. Compares the calculated and uncovered hashes for a match. The \"secure bootloader\" shoul
d be placed in protected memory on a given microcontroller. The Mynewt bootloader comprises two packages: The bootutil library (boot/bootutil) The boot application (apps/boot) The Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nmanner for the following two reasons: By keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders. By excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.",
"title": "Bootloader"
},
{
@@ -5157,63 +5157,58 @@
},
{
"location": "/os/modules/bootloader/bootloader/#image-format",
- "text": "The following definitions describe the image header format. #define IMAGE_MAGIC 0x96f3b83c #define IMAGE_MAGIC_NONE 0xffffffff struct image_version {\n uint8_t iv_major ;\n uint8_t iv_minor ;\n uint16_t iv_revision ;\n uint32_t iv_build_num ;\n}; /** Image header. All fields are in little endian byte order. */ struct image_header {\n uint32_t ih_magic ;\n uint16_t ih_tlv_size ; /* Trailing TLVs */ \n uint8_t ih_key_id ;\n uint8_t _pad1 ;\n uint16_t ih_hdr_size ;\n uint16_t _pad2 ;\n uint32_t ih_img_size ; /* Does not include header. */ \n uint32_t ih_flags ;\n struct image_version ih_ver ;\n uint32_t _pad3 ;\n}; The ih_hdr_size field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header. The following a
re the image header flags available. #define IMAGE_F_PIC 0x00000001 #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 #define IMAGE_HEADER_SIZE 32 Security data gets added as a footer at the end of the image. /* * 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 */",
+ "text": "The following definitions describe the image header format. #define IMAGE_MAGIC 0x96f3b83c #define IMAGE_MAGIC_NONE 0xffffffff struct image_version {\n uint8_t iv_major ;\n uint8_t iv_minor ;\n uint16_t iv_revision ;\n uint32_t iv_build_num ;\n}; /** Image header. All fields are in little endian byte order. */ struct image_header {\n uint32_t ih_magic ;\n uint16_t ih_tlv_size ; /* Trailing TLVs */ \n uint8_t ih_key_id ;\n uint8_t _pad1 ;\n uint16_t ih_hdr_s bok@bok . net 35 d33 ericmanganaro@gmail . com 42 d39 tam@proxy . co 55 d51 nathan@natb1 . com 110 d105 rvs@apache . orgize ;\n uint16_t _pad2 ;\n uint32_t ih_img_size ; /* Does not include header. */ \n uint32_t ih_flags ;\n struct image_version ih_ver ;\n uint32_t _pad3 ;\n}; The ih_hdr_size field indicates the length of the header, and therefore the\noffset of
the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header. The following are the image header flags available. #define IMAGE_F_PIC 0x00000001 #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 #define IMAGE_HEADER_SIZE 32 Optional type-length-value records (TLVs) containing image metadata are placed\nafter the end of the image. For example, security data gets added as a footer at the end of the image. /** Image trailer TLV format. All fields in little endian. */ struct image_tlv {\n uint8_t it_type ; /* IMAGE_TLV_[...]. */ \n uint8_t _pad ;\n uint16_t it_len /* Data length (not including TLV header). */ \n}; /* * Ima
ge 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 */",
"title": "Image Format"
},
{
- "location": "/os/modules/bootloader/bootloader/#flash-areas",
- "text": "Bootutil uses the same concept of \"flash areas\" as the nffs file system.\nBriefly, an area is a region of disk with the following properties:\n1. An area can be fully erased without affecting any other areas.\n2. A write to one area does not restrict writes to other areas. The areas used for image data must not be used for anything else. In\nparticular, these areas must be kept separate from the nffs file system.",
- "title": "Flash Areas"
+ "location": "/os/modules/bootloader/bootloader/#flash-map",
+ "text": "A Mynewt device's flash is partitioned according to its flash map . At a high\nlevel, the flash map maps numeric IDs to flash areas . A flash area is a\nregion of disk with the following properties: 1. An area can be fully erased without affecting any other areas.\n2. 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",
+ "title": "Flash Map"
},
{
"location": "/os/modules/bootloader/bootloader/#image-slots",
- "text": "A portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary 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\nallow for reliable image swapping. All areas used by image data (including the scratch area) must be the same\nsize.",
+ "text": "A portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary 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\nallow for reliable image swapping.",
"title": "Image Slots"
},
{
+ "location": "/os/modules/bootloader/bootloader/#boot-states",
+ "text": "Logically, you can think of a pair of flags associated with each image slot:\npending and confirmed. On startup, the boot loader determines the state of the\ndevice by inspecting each pair of flags. These flags have the following\nmeanings: pending: image gets tested on next reboot; absent subsequent confirm command,\n revert to original image on second reboot. confirmed: always use image unless excluded by a test image. In English, when the user wants to run the secondary image, they set the\npending flag for the second slot and reboot the device. On startup, the boot\nloader will swap the two images in flash, clear the secondary slot's pending\nflag, and run the newly-copied image in slot 0. This is a temporary state; if\nthe device reboots again, the boot loader swaps the images back to their\noriginal slots and boots into the original image. If the user doesn't want to\nrevert to the original state, they can make the current state permane
nt by\nsetting the confirmed flag in slot 0. Switching to an alternate image is a two-step process (set + confirm) to\nprevent a device from becoming \"bricked\" by bad firmware. If the device\ncrashes immediately upon booting the second image, the boot loader reverts to\nthe working image, rather than repeatedly rebooting into the bad image. The following set of tables illustrate the three possible states that the\ndevice can be in: | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | X | |\n---------------+--------+-------- \nImage 0 confirmed; |\nNo change on reboot |\n--------------------------------- \n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | X |\n confirmed | X | |\n---------------+--------+-------- \nImage 0 confirmed; |\nTest image 1 on next reboot |\n-------------
-------------------- \n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | | X |\n---------------+--------+-------- \nTesting image 0; |\nRevert to image 1 on next reboot |\n---------------------------------",
+ "title": "Boot States"
+ },
+ {
"location": "/os/modules/bootloader/bootloader/#boot-vector",
- "text": "If a vector file contains a version which doesn't correspond to an image\nactually present in flash, the boot loader deletes the file and procedes as\nthough the file was not present.",
+ "text": "At startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two\nrecords (called \"image trailers\"), one written at the end of each image slot.\nAn image trailer has the following structure: 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ MAGIC (16 octets) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ ~\n~ Swap status (128 * min-write-size * 3) ~\n~ ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Copy done | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Image OK | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ These records are at the end of each image slot. The offset immediately\nfollowing 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\nallows individual bytes to be written at arbitrary addresses, then\nmin-write-size is 1. If the hardware only allows writes at even addresses,\nthen min-write-size is 2, and so on. The fields are defined as follows: MAGIC: The following 16 bytes, written in host-byte-order: const uint32_t boot_img_magic[4] = {\n 0xf395c277,\n 0x7fefd260,\n 0x0f505235,\n 0x8079b62c,\n}; Swap status: A series of single-byte records. Each record corresponds to a\nflash sector in an image slot. A swap status byte indicate the location of\nthe corresponding sector data. During an image swa
p, image data is moved one\nsector at a time. The swap status is necessary for resuming a swap operation\nif the device rebooted before a swap operation completed. Copy done: A single byte indicating whether the image in this slot is\ncomplete (0x01=d bok@bok.net\n35d33 ericmanganaro@gmail.com\n42d39 tam@proxy.co\n55d51 nathan@natb1.com\n110d105 rvs@apache.orgone; 0xff=not done). Image OK: A single byte indicating whether the image in this slot has been\nconfirmed as good by the user (0x01=confirmed; 0xff=not confirmed). The boot vector records are structured around the limitations imposed by flash\nhardware. As a consequence, they do not have a very intuitive design, and it\nis difficult to get a sense of the state of the device just by looking at the\nboot vector. It is better to map all the possible vector states to the swap types (None, Test, Revert)\nvia a set of tables. These tables are reproduced below.\nIn these tables, the \"pending\" and \"confirmed\" fla
gs are shown for illustrative\npurposes; they are not actually present in the boot vector. State I\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Unset | Unset |\n image-ok | Any | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | X | |\n-----------------+--------+-------- \n swap: none |\n----------------------------------- \n\n\nState II\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Any | Good |\n image-ok | Any | N/A |\n-----------------+--------+-------- \n pending | | X |\n confirmed | X | |\n-----------------+--------+-------- \n swap: test |\n----------------------------------- \n\n\nState III\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Uns
et |\n image-ok | 0xff | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | | X |\n-----------------+--------+-------- \n swap: revert (test image running) |\n----------------------------------- \n\n\nState IV\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0x01 | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | X | |\n-----------------+--------+-------- \n swap: none (confirmed test image) |\n-----------------------------------",
"title": "Boot Vector"
},
{
- "location": "/os/modules/bootloader/bootloader/#boot-status",
- "text": "The boot status record allows the boot loader to recover in case it was reset\nwhile in the middle of an image swap operation. Image swapping is discussed\nlater in this document. struct boot_status_table {\n /** * For each field, a value of 0 means any . */ \n uint8_t bst_magic_slot0 ;\n uint8_t bst_magic_scratch ;\n uint8_t bst_copy_done_slot0 ;\n uint8_t bst_status_source ;\n}; struct boot_status {\n uint32_t idx ; /* Which area we re operating on */ \n uint8_t state ; /* Which part of the swapping process are we at */ \n};",
- "title": "Boot Status"
+ "location": "/os/modules/bootloader/bootloader/#high-level-operation",
+ "text": "With the terms defined, we can now explore the boot loader's operation. First,\na high-level overview of the boot process is presented. Then, the following\nsections describe each step of the process in more detail. Procedure: A. Inspect swap status region; is an interrupted swap is being resumed?\n Yes: Complete the partial swap operation; skip to step C.\n No: Proceed to step B. B. Insect boot vector; is a swap requested?\n Yes.\n 1. Is the requested image valid (integrity and security check)?\n Yes.\n a. Perform swap operation.\n b. Persist completion of swap procedure to boot vector.\n c. Proceed to step C.\n No.\n a. Erase invalid image.\n b. Persist failure of swap procedure to boot vector.\n c. Proceed to step C.\n No: Proceed to step C. C. Boot into image in slot 0.",
+ "title": "High-level Operation"
},
{
"location": "/os/modules/bootloader/bootloader/#image-swapping",
- "text": "If the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the process. The two images are swapped according to\nthe following procedure:",
+ "text": "The boot loader swaps the contents of the two image slots for two reasons:\n * User has issued an \"image test\" operation; the image in slot-1 should be\n run once (state II).\n * Test image rebooted without being confirmed; the boot loader should\n revert to the original image currently in slot-1 (state III). If the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the swap operation. The two images are swapped\naccording to the following procedure: 1. Determine how many flash sectors each image slot consists of. This\n number must be the same for both slots.\n2. Iterate the list of sector indices in descending order (i.e., starting\n with the greatest index); c
urrent element = index .\n b. Erase scratch area.\n c. Copy slot0[index] to scratch area.\n d. Write updated swap status (i).\n\n e. Erase slot1[index]\n f. Copy slot0[index] to slot1[index]\n - If these are the last sectors (i.e., first swap being perfomed),\n copy the full sector *except* the image trailer.\n - Else, copy entire sector contents.\n g. Write updated swap status (ii).\n\n h. Erase slot0[index].\n i. Copy scratch area slot0[index].\n j. Write updated swap status (iii).\n\n3. 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\ncan be written by the user at a later time. With the image trailer unwritten,\nthe user can test the image in slot 1 (i.e., transition to state II). The particulars of step 3 vary depending on whether an image is being tested or\nreverted:\n * test:\n o Write slot0.copy_done = 1\n (shou
ld now be in state III) * revert:\n o Write slot0.magic = BOOT_MAGIC\n o Write slot0.copy_done = 1\n o Write slot0.image_ok = 1\n (should now be in state IV)",
"title": "Image Swapping"
},
{
- "location": "/os/modules/bootloader/bootloader/#verifying-integrity-of-image",
- "text": "",
- "title": "Verifying integrity of image"
+ "location": "/os/modules/bootloader/bootloader/#swap-status",
+ "text": "The swap status region allows the boot loader to recover in case it restarts in\nthe middle of an image swap operation. The swap status region consists of a\nseries of single-byte records. These records are written independently, and\ntherefore must be padded according to the minimum write size imposed by the\nflash hardware. In the below figure, a min-write-size of 1 is assumed for\nsimplicity. The structure of the swap status region is illustrated below. In\nthis figure, a min-write-size of 1 is assumed for simplicity. 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-+-+-+-+-+-+-+-+-+-+\n|sec125,state 2 | |\n+-+-+-+-+-+-+-+-+ +\n~ ~\n~ [Records for indices 124 through 1 ~\n~ ~\n~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ And now, in English... Each image slot is partitioned into a sequence of flash sectors. If we were to\nenumerate the sectors in a single slot, starting at 0, we would have a list of\nsector indices. Since there are two image slots, each sector index would\ncorrespond to a pair of sectors. For example, sector index 0 corresponds to\nthe first sector in slot 0 and the first sector in slot 1. Furthermore, we\nimpose a limit of 128 in
dices. If an image slot consists of more than 128\nsectors, the flash layout is not compatible with this boot loader. Finally,\nreverse the list of indices such that the list starts with index 127 and ends\nwith 0. The swap status region is a representation of this reversed list. During a swap operation, each sector index transitions through four separate\nstates:\n 0. slot 0: image 0, slot 1: image 1, scratch: N/A\n 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1- s, erase 1)\n 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0- 1, erase 0)\n 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\nrecord to the swap status region. Logically, the boot loader only needs one\nrecord per sector index to keep track of the current swap state. However, due\nto limitations imposed by flash hardware, a record cannot be overwritten when\nan index's state chang
es. To solve this problem, the boot loader uses three\nrecords per sector index rather than just one. Each sector-state pair is represented as a set of three records. The record\nvalues map to the above four states as follows | rec0 | rec1 | rec2\n--------+------+------+------\nstate 0 | 0xff | 0xff | 0xff\nstate 1 | 0x01 | 0xff | 0xff\nstate 2 | 0x01 | 0x02 | 0xff\nstate 3 | 0x01 | 0x02 | 0x03 The swap status region can accommodate 128 sector indices. Hence, the size of\nthe region, in bytes, is 128 * min-write-size * 3. The number 128 is chosen\nsomewhat arbitrarily and will likely be made configurable. The only\nrequirement for the index count is that is is great enough to account for a\nmaximum-sized image (i.e., at least as great as the total sector count in an\nimage slot). If a device's image slots use less than 128 sectors, the first\nrecord that gets written will be somewhere in the middle of the region. For\nexample, if a slot uses 64 sectors, the first s
ector index that gets swapped is\n63, which corresponds to the exact halfway point within the region.",
+ "title": "Swap Status"
},
{
"location": "/os/modules/bootloader/bootloader/#reset-recovery",
- "text": "If the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot status file to determine how the image parts are placed in flash. If the boot status file indicates that the images are not contiguous, bootutil\ncompletes the swap operation that was in progress when the system was reset.\nIn other words, it applies the procedure defined in the previous section,\nmoving image 1 into slot 0 and image 0 into slot 1. If the boot status file\nindicates that an image part is present in the scratch area, this part is\ncopied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1. After the swap operation has been completed, the boot loader proceeds as though\nit had just been started.",
+ "text": "If the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot vector to determine how the image parts are distributed in flash. The first step is determine where the relevant swap status region is located.\nBecause this region is embedded within the image slots, its location in flash\nchanges during a swap operation. The below set of tables map boot vector\ncontents to swap status location. In these tables, the \"source\" field\nindicates where the swap status region is located. | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0x01 | N/A |\n----------+------------+------------ \nsource: none |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any
|\ncopy-done | 0xff | N/A |\n----------+------------+------------ \nsource: slot 0 |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Any | Good |\ncopy-done | Any | N/A |\n----------+------------+------------ \nsource: scratch |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Unset | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------|\nsource: varies |\n------------------------------------+------------------------------+\nThis represents one of two cases: |\no No swaps ever (no status to read, so no harm in checking). |\no Mid-revert; status in slot 0. |\n------------------------------------------
------------------------- If the swap status region indicates that the images are not contiguous,\nbootutil completes the swap operation that was in progress when the system was\nreset. In other words, it applies the procedure defined in the previous\nsection, moving image 1 into slot 0 and image 0 into slot 1. If the boot\nstatus file indicates that an image part is present in the scratch area, this\npart is copied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1. After the swap operation has been completed, the boot loader proceeds as though\nit had just been started.",
"title": "Reset Recovery"
},
{
- "location": "/os/modules/bootloader/bootloader/#api",
- "text": "",
- "title": "API"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#dependencies",
- "text": "The bootloader depends on the following OS kernel functions: The bootloader does not depend on any flash file system.",
- "title": "Dependencies"
+ "location": "/os/modules/bootloader/bootloader/#integrity-check",
+ "text": "An image is checked for integrity immediately before it gets copied into the\nprimary slot. If the boot loader doesn't perform an image swap, then it\ndoesn't perform an integrity check. During the integrity check, the boot loader verifies the following aspects of\nan image:\n * 32-bit magic number must be correct (0x96f3b83c).\n * Image must contain a SHA256 TLV.\n * Calculated SHA256 must matche SHA256 TLV contents.\n * Image may contain a signature TLV. If it does, its contents must be\n verifiable using a key embedded in the boot loader.",
+ "title": "Integrity Check"
},
{
- "location": "/os/modules/bootloader/bootloader/#list-of-functions",
- "text": "The functions available in bootloader are:",
- "title": "List of Functions"
+ "location": "/os/modules/bootloader/bootloader/#image-signing-and-verification",
+ "text": "As indicated above, the final step of the integrity check is signature\nverification. The boot loader can have one or more public keys embedded in it\nat build time. During signature verification, the boot loader verifies that an\nimage was signed with a private key that corresponds to one of its public keys.\nThe image signature TLV indicates the index of the key that is has been signed\nwith. The boot loader uses this index to identify the corresponding public\nkey. For information on embedding public keys in the boot loader, as well as\nproducing signed images, see: boot/bootutil/signed_images.md",
+ "title": "Image Signing and Verification"
},
{
"location": "/os/modules/bootloader/boot_build_status/",
[4/4] incubator-mynewt-site git commit: Updated bootloader doc
Posted by ad...@apache.org.
Updated bootloader doc
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/6e429bad
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/6e429bad
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/6e429bad
Branch: refs/heads/asf-site
Commit: 6e429bad90d6555ef055f95093edba1ef33016b3
Parents: f78bd41
Author: aditihilbert <ad...@runtime.io>
Authored: Tue Dec 13 17:17:43 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Tue Dec 13 17:17:43 2016 -0800
----------------------------------------------------------------------
develop/mkdocs/search_index.json | 59 ++-
.../os/modules/bootloader/bootloader/index.html | 472 ++++++++++++++++---
latest/mkdocs/search_index.json | 59 ++-
.../os/modules/bootloader/bootloader/index.html | 472 ++++++++++++++++---
4 files changed, 890 insertions(+), 172 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6e429bad/develop/mkdocs/search_index.json
----------------------------------------------------------------------
diff --git a/develop/mkdocs/search_index.json b/develop/mkdocs/search_index.json
index 9cada04..22b3186 100644
--- a/develop/mkdocs/search_index.json
+++ b/develop/mkdocs/search_index.json
@@ -5142,12 +5142,12 @@
},
{
"location": "/os/modules/bootloader/bootloader/",
- "text": "Bootloader\n\n\nThe \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:\n\n\n\n\nCalculates hash of the image.\n\n\nUses public key to uncover hash value from included signature. \n\n\nCompares the calculated and uncovered hashes for a match.\n\n\n\n\nThe \"secure bootloader\" should be placed in protected memory on a given microcontroller.\n\n\nThe Mynewt code is structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot load
er functionality is separated in this\nmanner for the following two reasons:\n\n\n\n\nBy keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders.\n\n\nBy excluding the last boot step from the library, the rest of the code can\n be tested in a sim environment.\n\n\n\n\nLimitations\n\n\nThe boot loader currently only supports images with the following\ncharacteristics:\n\n\n\n\nBuilt to run from flash.\n\n\nBuild to run from a fixed location (i.e., position-independent).\n\n\n\n\nImage Format\n\n\nThe following definitions describe the image header format.\n\n\n#define IMAGE_MAGIC 0x96f3b83c\n\n\n#define IMAGE_MAGIC_NONE 0xffffffff\n\n\n\nstruct\n \nimage_version\n {\n \nuint8_t\n \niv_major\n;\n \nuint8_t\n \niv_minor\n;\n \nuint16_t\n \niv_revision\n;\n \nuint32_t\n \niv_build_num\n;\n};\n\n\n/** Image header. All fields are in little endian byte order. */\n\n\nstruct\n \nimage_header\n
{\n \nuint32_t\n \nih_magic\n;\n \nuint16_t\n \nih_tlv_size\n; \n/* Trailing TLVs */\n\n \nuint8_t\n \nih_key_id\n;\n \nuint8_t\n \n_pad1\n;\n \nuint16_t\n \nih_hdr_size\n;\n \nuint16_t\n \n_pad2\n;\n \nuint32_t\n \nih_img_size\n; \n/* Does not include header. */\n\n \nuint32_t\n \nih_flags\n;\n \nstruct\n \nimage_version\n \nih_ver\n;\n \nuint32_t\n \n_pad3\n;\n};\n\n\n\n\n\nThe \nih_hdr_size\n field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header.\n\n\nThe following are the image header flags available.\n\n\n#define IMAGE_F_PIC 0x00000001\n\n\n#define IMAGE_F_SHA256 0x00000002 \n/* Image contains hash TLV */\n\n\n#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 \n/* PKCS15 w/RSA and SHA */\n\n\n#define IMAGE_F_ECDSA224_SHA256 0x00000008 \n/* ECDSA256 over SHA256 */\n\n\n
#define IMAGE_F_NON_BOOTABLE 0x00000010\n\n\n#define IMAGE_HEADER_SIZE 32\n\n\n\n\n\n\nSecurity data gets added as a footer at the end of the image.\n\n\n/*\n\n\n * Image trailer TLV types.\n\n\n */\n\n\n#define IMAGE_TLV_SHA256 1 \n/* SHA256 of image hdr and body */\n\n\n#define IMAGE_TLV_RSA2048 2 \n/* RSA2048 of hash output */\n\n\n#define IMAGE_TLV_ECDSA224 3 \n/* ECDSA of hash output */\n\n\n\n\n\n\nFlash Areas\n\n\nBootutil uses the same concept of \"flash areas\" as the nffs file system.\nBriefly, an area is a region of disk with the following properties:\n1. An area can be fully erased without affecting any other areas.\n2. A write to one area does not restrict writes to other areas.\n\n\nThe areas used for image data must not be used for anything else. In\nparticular, these areas must be kept separate from the nffs file system.\n\n\nImage Slots\n\n\nA portion of the flash memory is partitioned into two image slots: a p
rimary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary slot, it must swap the two images in flash prior to booting.\n\n\nIn addition to the two image slots, the boot loader requires a scratch area to\nallow for reliable image swapping.\n\n\nAll areas used by image data (including the scratch area) must be the same\nsize.\n\n\nBoot Vector\n\n\nIf a vector file contains a version which doesn't correspond to an image\nactually present in flash, the boot loader deletes the file and procedes as\nthough the file was not present.\n\n\nBoot Status\n\n\nThe boot status record allows the boot loader to recover in case it was reset\nwhile in the middle of an image swap operation. Image swapping is discussed\nlater in this document. \n\n\nstruct\n \nboot_status_table\n {\n \n/**\n\n\n * For ea
ch field, a value of 0 means \nany\n.\n\n\n */\n\n \nuint8_t\n \nbst_magic_slot0\n;\n \nuint8_t\n \nbst_magic_scratch\n;\n \nuint8_t\n \nbst_copy_done_slot0\n;\n \nuint8_t\n \nbst_status_source\n;\n};\n\n\n\n\n\nstruct\n \nboot_status\n {\n \nuint32_t\n \nidx\n; \n/* Which area we\nre operating on */\n\n \nuint8_t\n \nstate\n; \n/* Which part of the swapping process are we at */\n\n};\n\n\n\n\n\nImage Swapping\n\n\nIf the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the process. The two images are swapped according to\nthe following procedure:\n\n\nVerifying integrity of image\n\n\nReset Recovery\n\n\nIf the boot loader resets in the middle of a swap operation, the two
images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot status file to determine how the image parts are placed in flash.\n\n\nIf the boot status file indicates that the images are not contiguous, bootutil\ncompletes the swap operation that was in progress when the system was reset.\nIn other words, it applies the procedure defined in the previous section,\nmoving image 1 into slot 0 and image 0 into slot 1. If the boot status file\nindicates that an image part is present in the scratch area, this part is\ncopied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1.\n\n\nAfter the swap operation has been completed, the boot loader proceeds as though\nit had just been started.\n\n\nAPI\n\n\nExample\n\n\nDependencies\n\n\nThe bootloader depends on the following OS kernel functions:\n\n\nThe bootloader does not depend on any flash file system.\n\n\nLi
st of Functions\n\n\n\n\nThe functions available in bootloader are:",
+ "text": "Bootloader\n\n\nThe \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process.\n\n\nThe bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:\n\n\n\n\nCalculates hash of the image.\n\n\nUses public key to uncover hash value from included signature. \n\n\nCompares the calculated and uncovered hashes for a match
.\n\n\n\n\nThe \"secure bootloader\" should be placed in protected memory on a given microcontroller.\n\n\nThe Mynewt bootloader comprises two packages:\n\n\n\n\nThe bootutil library (boot/bootutil)\n\n\nThe boot application (apps/boot)\n\n\n\n\nThe Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nmanner for the following two reasons:\n\n\n\n\nBy keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders.\n\n\nBy excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.\n\n\n\n\nLimitations\n\n\nThe boot loader currently only supports images with the following\ncha
racteristics:\n\n\n\n\nBuilt to run from flash.\n\n\nBuild to run from a fixed location (i.e., position-independent).\n\n\n\n\nImage Format\n\n\nThe following definitions describe the image header format.\n\n\n#define IMAGE_MAGIC 0x96f3b83c\n\n\n#define IMAGE_MAGIC_NONE 0xffffffff\n\n\n\nstruct\n \nimage_version\n {\n \nuint8_t\n \niv_major\n;\n \nuint8_t\n \niv_minor\n;\n \nuint16_t\n \niv_revision\n;\n \nuint32_t\n \niv_build_num\n;\n};\n\n\n/** Image header. All fields are in little endian byte order. */\n\n\nstruct\n \nimage_header\n {\n \nuint32_t\n \nih_magic\n;\n \nuint16_t\n \nih_tlv_size\n; \n/* Trailing TLVs */\n\n \nuint8_t\n \nih_key_id\n;\n \nuint8_t\n \n_pad1\n;\n \nuint16_t\n \nih_hdr_s\n \nbok@bok\n.\nnet\n\n\n35\nd33\n\n\n \nericmanganaro@gmail\n.\ncom\n\n\n42\nd39\n\n\n \ntam@proxy\n.\nco\n\n\n55\nd51\n\n\n \nnathan@natb1\n.\ncom\n\n\n110\nd105\n\n\n \nrvs@apache\n.\norgize\n;\n \nuint16_t\n \n_pad2\n;\n
\nuint32_t\n \nih_img_size\n; \n/* Does not include header. */\n\n \nuint32_t\n \nih_flags\n;\n \nstruct\n \nimage_version\n \nih_ver\n;\n \nuint32_t\n \n_pad3\n;\n};\n\n\n\n\n\nThe \nih_hdr_size\n field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header.\n\n\nThe following are the image header flags available.\n\n\n#define IMAGE_F_PIC 0x00000001\n\n\n#define IMAGE_F_SHA256 0x00000002 \n/* Image contains hash TLV */\n\n\n#define IMAGE_F_PKCS15_RSA2048_SHA256 0x00000004 \n/* PKCS15 w/RSA and SHA */\n\n\n#define IMAGE_F_ECDSA224_SHA256 0x00000008 \n/* ECDSA256 over SHA256 */\n\n\n#define IMAGE_F_NON_BOOTABLE 0x00000010\n\n\n#define IMAGE_HEADER_SIZE 32\n\n\n\n\n\n\nOptional type-length-value records (TLVs) containing image metadata are placed\nafter the end of the image. For examp
le, security data gets added as a footer at the end of the image.\n\n\n/** Image trailer TLV format. All fields in little endian. */\n\n\nstruct\n \nimage_tlv\n {\n \nuint8_t\n \nit_type\n; \n/* IMAGE_TLV_[...]. */\n\n \nuint8_t\n \n_pad\n;\n \nuint16_t\n \nit_len\n \n/* Data length (not including TLV header). */\n\n};\n\n\n/*\n\n\n * Image trailer TLV types.\n\n\n */\n\n\n#define IMAGE_TLV_SHA256 1 \n/* SHA256 of image hdr and body */\n\n\n#define IMAGE_TLV_RSA2048 2 \n/* RSA2048 of hash output */\n\n\n#define IMAGE_TLV_ECDSA224 3 \n/* ECDSA of hash output */\n\n\n\n\n\n\nFlash Map\n\n\nA Mynewt device's flash is partitioned according to its \nflash map\n. At a high\nlevel, the flash map maps numeric IDs to \nflash areas\n. A flash area is a\nregion of disk with the following properties:\n\n\n1. An area can be fully erased without affecting any other areas.\n2. A write to one area does not restrict writes to other areas.\n\n\n\
n\n\nThe boot loader uses the following flash areas:\n\n\n#define FLASH_AREA_BOOTLOADER 0\n\n\n#define FLASH_AREA_IMAGE_0 1\n\n\n#define FLASH_AREA_IMAGE_1 2\n\n\n#define FLASH_AREA_IMAGE_SCRATCH 3\n\n\n\n\n\n\nImage Slots\n\n\nA portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary slot, it must swap the two images in flash prior to booting.\n\n\nIn addition to the two image slots, the boot loader requires a scratch area to\nallow for reliable image swapping.\n\n\nBoot States\n\n\nLogically, you can think of a pair of flags associated with each image slot:\npending and confirmed. On startup, the boot loader determines the state of the\ndevice
by inspecting each pair of flags. These flags have the following\nmeanings:\n\n\n\n\npending: image gets tested on next reboot; absent subsequent confirm command,\n revert to original image on second reboot.\n\n\nconfirmed: always use image unless excluded by a test image.\n\n\n\n\nIn English, when the user wants to run the secondary image, they set the\npending flag for the second slot and reboot the device. On startup, the boot\nloader will swap the two images in flash, clear the secondary slot's pending\nflag, and run the newly-copied image in slot 0. This is a temporary state; if\nthe device reboots again, the boot loader swaps the images back to their\noriginal slots and boots into the original image. If the user doesn't want to\nrevert to the original state, they can make the current state permanent by\nsetting the confirmed flag in slot 0.\n\n\nSwitching to an alternate image is a two-step process (set + confirm) to\nprevent a device from becoming \"bricked\" b
y bad firmware. If the device\ncrashes immediately upon booting the second image, the boot loader reverts to\nthe working image, rather than repeatedly rebooting into the bad image.\n\n\nThe following set of tables illustrate the three possible states that the\ndevice can be in:\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | X | |\n---------------+--------+--------\n\nImage 0 confirmed; |\nNo change on reboot |\n---------------------------------\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | X |\n confirmed | X | |\n---------------+--------+--------\n\nImage 0 confirmed; |\nTest image 1 on next reboot |\n---------------------------------\n\n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed |
| X |\n---------------+--------+--------\n\nTesting image 0; |\nRevert to image 1 on next reboot |\n---------------------------------\n\n\n\n\n\n\nBoot Vector\n\n\nAt startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two\nrecords (called \"image trailers\"), one written at the end of each image slot.\nAn image trailer has the following structure:\n\n\n 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ MAGIC (16 octets) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ ~\n~ Swap status (128 * min-write-size * 3) ~\n~
~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Copy done | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Image OK | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n\n\n\n\n\nThese records are at the end of each image slot. The offset immediately\nfollowing such a record represents the start of the next flash area.\n\n\nNote: \"min-write-size\" is a property of the flash hardware. If the hardware\nallows individual bytes to be written at arbitrary addresses, then\nmin-write-size is 1. If the hardware only allows writes at even addresses,\nthen min-write-size is 2, and so on.\n\n\nThe fields are defined as follows:\n\n\n\n\n\n\nMAGIC: The following 16 bytes, written in host-byte-order:\n\n\nconst uint32_t boot_img_magic[4] = {\n 0xf395c277,\n 0x7fefd260,\n 0x0f505235,\n 0x8079b62c,\n};\n\n
\n\n\n\n\nSwap status: A series of single-byte records. Each record corresponds to a\nflash sector in an image slot. A swap status byte indicate the location of\nthe corresponding sector data. During an image swap, image data is moved one\nsector at a time. The swap status is necessary for resuming a swap operation\nif the device rebooted before a swap operation completed.\n\n\n\n\n\n\nCopy done: A single byte indicating whether the image in this slot is\ncomplete (0x01=d\n bok@bok.net\n35d33\n\n ericmanganaro@gmail.com\n42d39\n\n tam@proxy.co\n55d51\n\n nathan@natb1.com\n110d105\n\n rvs@apache.orgone; 0xff=not done).\n\n\n\n\n\n\nImage OK: A single byte indicating whether the image in this slot has been\nconfirmed as good by the user (0x01=confirmed; 0xff=not confirmed).\n\n\n\n\n\n\nThe boot vector records are structured around the limitations imposed by flash\nhardware. As a consequence, they do not have a very intuitive design, and it\nis difficult to get a sense of the sta
te of the device just by looking at the\nboot vector. It is better to map all the possible vector states to the swap types (None, Test, Revert)\nvia a set of tables. These tables are reproduced below.\nIn these tables, the \"pending\" and \"confirmed\" flags are shown for illustrative\npurposes; they are not actually present in the boot vector.\n\n\nState I\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Unset | Unset |\n image-ok | Any | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: none |\n-----------------------------------\n\n\n\nState II\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Any | Good |\n image-ok | Any | N/A |\n-----------------+--------+--------\n\n pending | | X |\n co
nfirmed | X | |\n-----------------+--------+--------\n\n swap: test |\n-----------------------------------\n\n\n\nState III\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0xff | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | | X |\n-----------------+--------+--------\n\n swap: revert (test image running) |\n-----------------------------------\n\n\n\nState IV\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0x01 | N/A |\n-----------------+--------+--------\n\n pending | | |\n confirmed | X | |\n-----------------+--------+--------\n\n swap: none (confirmed test image) |\n-----------------------------------\n\n\n\n\n\n\nHigh-level Operation\n\n\nWith the terms defin
ed, we can now explore the boot loader's operation. First,\na high-level overview of the boot process is presented. Then, the following\nsections describe each step of the process in more detail.\n\n\nProcedure:\n\n\nA. Inspect swap status region; is an interrupted swap is being resumed?\n Yes: Complete the partial swap operation; skip to step C.\n No: Proceed to step B.\n\n\nB. Insect boot vector; is a swap requested?\n Yes.\n 1. Is the requested image valid (integrity and security check)?\n Yes.\n a. Perform swap operation.\n b. Persist completion of swap procedure to boot vector.\n c. Proceed to step C.\n No.\n a. Erase invalid image.\n b. Persist failure of swap procedure to boot vector.\n c. Proceed to step C.\n No: Proceed to step C.\n\n\nC. Boot into image in slot 0.\n\n\nImage Swapping\n\n\nThe boot loader swaps the contents of the two image sl
ots for two reasons:\n * User has issued an \"image test\" operation; the image in slot-1 should be\n run once (state II).\n * Test image rebooted without being confirmed; the boot loader should\n revert to the original image currently in slot-1 (state III).\n\n\nIf the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the swap operation. The two images are swapped\naccording to the following procedure:\n\n\n1. Determine how many flash sectors each image slot consists of. This\n number must be the same for both slots.\n2. Iterate the list of sector indices in descending order (i.e., starting\n with the greatest index); current element = \nindex\n.\n b. Erase scratch area.\n c. Cop
y slot0[index] to scratch area.\n d. Write updated swap status (i).\n\n e. Erase slot1[index]\n f. Copy slot0[index] to slot1[index]\n - If these are the last sectors (i.e., first swap being perfomed),\n copy the full sector *except* the image trailer.\n - Else, copy entire sector contents.\n g. Write updated swap status (ii).\n\n h. Erase slot0[index].\n i. Copy scratch area slot0[index].\n j. Write updated swap status (iii).\n\n3. Persist completion of swap procedure to slot 0 image trailer.\n\n\n\n\n\nThe additional caveats in step 2f are necessary so that the slot 1 image trailer\ncan be written by the user at a later time. With the image trailer unwritten,\nthe user can test the image in slot 1 (i.e., transition to state II).\n\n\nThe particulars of step 3 vary depending on whether an image is being tested or\nreverted:\n * test:\n o Write slot0.copy_done = 1\n (should now be in state III)\n\n\n* revert:\n o Write
slot0.magic = BOOT_MAGIC\n o Write slot0.copy_done = 1\n o Write slot0.image_ok = 1\n (should now be in state IV)\n\n\n\n\n\nSwap Status\n\n\nThe swap status region allows the boot loader to recover in case it restarts in\nthe middle of an image swap operation. The swap status region consists of a\nseries of single-byte records. These records are written independently, and\ntherefore must be padded according to the minimum write size imposed by the\nflash hardware. In the below figure, a min-write-size of 1 is assumed for\nsimplicity. The structure of the swap status region is illustrated below. In\nthis figure, a min-write-size of 1 is assumed for simplicity.\n\n\n 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
+-+-+-+-+-+-+-+-+-+-+\n|sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec125,state 2 | |\n+-+-+-+-+-+-+-+-+ +\n~ ~\n~ [Records for indices 124 through 1 ~\n~ ~\n~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n\n\n\n\n\nAnd now, in English...\n\n\nEach image slot is partitioned into a sequence of flash sectors. If we were to\nenumerate the sectors in a single slot, starting at 0, we would have a list of\nsector indices. Since there are two image slots, each sector index would\ncorrespond to a pair of sector
s. For example, sector index 0 corresponds to\nthe first sector in slot 0 and the first sector in slot 1. Furthermore, we\nimpose a limit of 128 indices. If an image slot consists of more than 128\nsectors, the flash layout is not compatible with this boot loader. Finally,\nreverse the list of indices such that the list starts with index 127 and ends\nwith 0. The swap status region is a representation of this reversed list.\n\n\nDuring a swap operation, each sector index transitions through four separate\nstates:\n 0. slot 0: image 0, slot 1: image 1, scratch: N/A\n 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1-\ns, erase 1)\n 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0-\n1, erase 0)\n 3. slot 0: image 1, slot 1: image 0, scratch: N/A (s-\n0)\n\n\nEach time a sector index transitions to a new state, the boot loader writes a\nrecord to the swap status region. Logically, the boot loader only needs one\nrecord per sector ind
ex to keep track of the current swap state. However, due\nto limitations imposed by flash hardware, a record cannot be overwritten when\nan index's state changes. To solve this problem, the boot loader uses three\nrecords per sector index rather than just one.\n\n\nEach sector-state pair is represented as a set of three records. The record\nvalues map to the above four states as follows\n\n\n | rec0 | rec1 | rec2\n--------+------+------+------\nstate 0 | 0xff | 0xff | 0xff\nstate 1 | 0x01 | 0xff | 0xff\nstate 2 | 0x01 | 0x02 | 0xff\nstate 3 | 0x01 | 0x02 | 0x03\n\n\n\n\n\nThe swap status region can accommodate 128 sector indices. Hence, the size of\nthe region, in bytes, is 128 * min-write-size * 3. The number 128 is chosen\nsomewhat arbitrarily and will likely be made configurable. The only\nrequirement for the index count is that is is great enough to account for a\nmaximum-sized image (i.e., at least as great as the total sector count in an\nimage slot). If a device
's image slots use less than 128 sectors, the first\nrecord that gets written will be somewhere in the middle of the region. For\nexample, if a slot uses 64 sectors, the first sector index that gets swapped is\n63, which corresponds to the exact halfway point within the region.\n\n\nReset Recovery\n\n\nIf the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot vector to determine how the image parts are distributed in flash.\n\n\nThe first step is determine where the relevant swap status region is located.\nBecause this region is embedded within the image slots, its location in flash\nchanges during a swap operation. The below set of tables map boot vector\ncontents to swap status location. In these tables, the \"source\" field\nindicates where the swap status region is located.\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Go
od | Any |\ncopy-done | 0x01 | N/A |\n----------+------------+------------\n\nsource: none |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------\n\nsource: slot 0 |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Any | Good |\ncopy-done | Any | N/A |\n----------+------------+------------\n\nsource: scratch |\n------------------------------------\n\n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Unset | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------|\nsource: varies |\n------------------------
------------+------------------------------+\nThis represents one of two cases: |\no No swaps ever (no status to read, so no harm in checking). |\no Mid-revert; status in slot 0. |\n-------------------------------------------------------------------\n\n\n\n\n\n\nIf the swap status region indicates that the images are not contiguous,\nbootutil completes the swap operation that was in progress when the system was\nreset. In other words, it applies the procedure defined in the previous\nsection, moving image 1 into slot 0 and image 0 into slot 1. If the boot\nstatus file indicates that an image part is present in the scratch area, this\npart is copied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1.\n\n\nAfter the swap operation has been completed, the boot loader proceeds as though\nit had just been started.\n\n
\nIntegrity Check\n\n\nAn image is checked for integrity immediately before it gets copied into the\nprimary slot. If the boot loader doesn't perform an image swap, then it\ndoesn't perform an integrity check.\n\n\nDuring the integrity check, the boot loader verifies the following aspects of\nan image:\n * 32-bit magic number must be correct (0x96f3b83c).\n * Image must contain a SHA256 TLV.\n * Calculated SHA256 must matche SHA256 TLV contents.\n * Image \nmay\n contain a signature TLV. If it does, its contents must be\n verifiable using a key embedded in the boot loader.\n\n\nImage Signing and Verification\n\n\nAs indicated above, the final step of the integrity check is signature\nverification. The boot loader can have one or more public keys embedded in it\nat build time. During signature verification, the boot loader verifies that an\nimage was signed with a private key that corresponds to one of its public keys.\nThe image signature TLV indicates the index
of the key that is has been signed\nwith. The boot loader uses this index to identify the corresponding public\nkey.\n\n\nFor information on embedding public keys in the boot loader, as well as\nproducing signed images, see: boot/bootutil/signed_images.md",
"title": "toc"
},
{
"location": "/os/modules/bootloader/bootloader/#bootloader",
- "text": "The \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it: Calculates hash of the image. Uses public key to uncover hash value from included signature. Compares the calculated and uncovered hashes for a match. The \"secure bootloader\" should be placed in protected memory on a given microcontroller. The Mynewt code is structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nman
ner for the following two reasons: By keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders. By excluding the last boot step from the library, the rest of the code can\n be tested in a sim environment.",
+ "text": "The \"bootloader\" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it: Calculates hash of the image. Uses public key to uncover hash value from included signature. Compares the calculated and uncovered hashes for a match. The \"secure bootloader\" shoul
d be placed in protected memory on a given microcontroller. The Mynewt bootloader comprises two packages: The bootutil library (boot/bootutil) The boot application (apps/boot) The Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an\narchitecture-specific project. Boot loader functionality is separated in this\nmanner for the following two reasons: By keeping architecture-dependent code separate, the bootutil library can be\n reused among several boot loaders. By excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.",
"title": "Bootloader"
},
{
@@ -5157,63 +5157,58 @@
},
{
"location": "/os/modules/bootloader/bootloader/#image-format",
- "text": "The following definitions describe the image header format. #define IMAGE_MAGIC 0x96f3b83c #define IMAGE_MAGIC_NONE 0xffffffff struct image_version {\n uint8_t iv_major ;\n uint8_t iv_minor ;\n uint16_t iv_revision ;\n uint32_t iv_build_num ;\n}; /** Image header. All fields are in little endian byte order. */ struct image_header {\n uint32_t ih_magic ;\n uint16_t ih_tlv_size ; /* Trailing TLVs */ \n uint8_t ih_key_id ;\n uint8_t _pad1 ;\n uint16_t ih_hdr_size ;\n uint16_t _pad2 ;\n uint32_t ih_img_size ; /* Does not include header. */ \n uint32_t ih_flags ;\n struct image_version ih_ver ;\n uint32_t _pad3 ;\n}; The ih_hdr_size field indicates the length of the header, and therefore the\noffset of the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header. The following a
re the image header flags available. #define IMAGE_F_PIC 0x00000001 #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 #define IMAGE_HEADER_SIZE 32 Security data gets added as a footer at the end of the image. /* * 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 */",
+ "text": "The following definitions describe the image header format. #define IMAGE_MAGIC 0x96f3b83c #define IMAGE_MAGIC_NONE 0xffffffff struct image_version {\n uint8_t iv_major ;\n uint8_t iv_minor ;\n uint16_t iv_revision ;\n uint32_t iv_build_num ;\n}; /** Image header. All fields are in little endian byte order. */ struct image_header {\n uint32_t ih_magic ;\n uint16_t ih_tlv_size ; /* Trailing TLVs */ \n uint8_t ih_key_id ;\n uint8_t _pad1 ;\n uint16_t ih_hdr_s bok@bok . net 35 d33 ericmanganaro@gmail . com 42 d39 tam@proxy . co 55 d51 nathan@natb1 . com 110 d105 rvs@apache . orgize ;\n uint16_t _pad2 ;\n uint32_t ih_img_size ; /* Does not include header. */ \n uint32_t ih_flags ;\n struct image_version ih_ver ;\n uint32_t _pad3 ;\n}; The ih_hdr_size field indicates the length of the header, and therefore the\noffset of
the image itself. This field provides for backwards compatibility in\ncase of changes to the format of the image header. The following are the image header flags available. #define IMAGE_F_PIC 0x00000001 #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 #define IMAGE_HEADER_SIZE 32 Optional type-length-value records (TLVs) containing image metadata are placed\nafter the end of the image. For example, security data gets added as a footer at the end of the image. /** Image trailer TLV format. All fields in little endian. */ struct image_tlv {\n uint8_t it_type ; /* IMAGE_TLV_[...]. */ \n uint8_t _pad ;\n uint16_t it_len /* Data length (not including TLV header). */ \n}; /* * Ima
ge 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 */",
"title": "Image Format"
},
{
- "location": "/os/modules/bootloader/bootloader/#flash-areas",
- "text": "Bootutil uses the same concept of \"flash areas\" as the nffs file system.\nBriefly, an area is a region of disk with the following properties:\n1. An area can be fully erased without affecting any other areas.\n2. A write to one area does not restrict writes to other areas. The areas used for image data must not be used for anything else. In\nparticular, these areas must be kept separate from the nffs file system.",
- "title": "Flash Areas"
+ "location": "/os/modules/bootloader/bootloader/#flash-map",
+ "text": "A Mynewt device's flash is partitioned according to its flash map . At a high\nlevel, the flash map maps numeric IDs to flash areas . A flash area is a\nregion of disk with the following properties: 1. An area can be fully erased without affecting any other areas.\n2. 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",
+ "title": "Flash Map"
},
{
"location": "/os/modules/bootloader/bootloader/#image-slots",
- "text": "A portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary 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\nallow for reliable image swapping. All areas used by image data (including the scratch area) must be the same\nsize.",
+ "text": "A portion of the flash memory is partitioned into two image slots: a primary\nslot and a secondary slot. The boot loader will only run an image from the\nprimary slot, so images must be built such that they can run from that fixed\nlocation in flash. If the boot loader needs to run the image resident in the\nsecondary 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\nallow for reliable image swapping.",
"title": "Image Slots"
},
{
+ "location": "/os/modules/bootloader/bootloader/#boot-states",
+ "text": "Logically, you can think of a pair of flags associated with each image slot:\npending and confirmed. On startup, the boot loader determines the state of the\ndevice by inspecting each pair of flags. These flags have the following\nmeanings: pending: image gets tested on next reboot; absent subsequent confirm command,\n revert to original image on second reboot. confirmed: always use image unless excluded by a test image. In English, when the user wants to run the secondary image, they set the\npending flag for the second slot and reboot the device. On startup, the boot\nloader will swap the two images in flash, clear the secondary slot's pending\nflag, and run the newly-copied image in slot 0. This is a temporary state; if\nthe device reboots again, the boot loader swaps the images back to their\noriginal slots and boots into the original image. If the user doesn't want to\nrevert to the original state, they can make the current state permane
nt by\nsetting the confirmed flag in slot 0. Switching to an alternate image is a two-step process (set + confirm) to\nprevent a device from becoming \"bricked\" by bad firmware. If the device\ncrashes immediately upon booting the second image, the boot loader reverts to\nthe working image, rather than repeatedly rebooting into the bad image. The following set of tables illustrate the three possible states that the\ndevice can be in: | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | X | |\n---------------+--------+-------- \nImage 0 confirmed; |\nNo change on reboot |\n--------------------------------- \n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | X |\n confirmed | X | |\n---------------+--------+-------- \nImage 0 confirmed; |\nTest image 1 on next reboot |\n-------------
-------------------- \n\n | slot-0 | slot-1 |\n---------------+--------+--------|\n pending | | |\n confirmed | | X |\n---------------+--------+-------- \nTesting image 0; |\nRevert to image 1 on next reboot |\n---------------------------------",
+ "title": "Boot States"
+ },
+ {
"location": "/os/modules/bootloader/bootloader/#boot-vector",
- "text": "If a vector file contains a version which doesn't correspond to an image\nactually present in flash, the boot loader deletes the file and procedes as\nthough the file was not present.",
+ "text": "At startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two\nrecords (called \"image trailers\"), one written at the end of each image slot.\nAn image trailer has the following structure: 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ MAGIC (16 octets) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ ~\n~ Swap status (128 * min-write-size * 3) ~\n~ ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Copy done | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n| Image OK | 0xff padding (up to min-write-sz - 1) ~\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ These records are at the end of each image slot. The offset immediately\nfollowing 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\nallows individual bytes to be written at arbitrary addresses, then\nmin-write-size is 1. If the hardware only allows writes at even addresses,\nthen min-write-size is 2, and so on. The fields are defined as follows: MAGIC: The following 16 bytes, written in host-byte-order: const uint32_t boot_img_magic[4] = {\n 0xf395c277,\n 0x7fefd260,\n 0x0f505235,\n 0x8079b62c,\n}; Swap status: A series of single-byte records. Each record corresponds to a\nflash sector in an image slot. A swap status byte indicate the location of\nthe corresponding sector data. During an image swa
p, image data is moved one\nsector at a time. The swap status is necessary for resuming a swap operation\nif the device rebooted before a swap operation completed. Copy done: A single byte indicating whether the image in this slot is\ncomplete (0x01=d bok@bok.net\n35d33 ericmanganaro@gmail.com\n42d39 tam@proxy.co\n55d51 nathan@natb1.com\n110d105 rvs@apache.orgone; 0xff=not done). Image OK: A single byte indicating whether the image in this slot has been\nconfirmed as good by the user (0x01=confirmed; 0xff=not confirmed). The boot vector records are structured around the limitations imposed by flash\nhardware. As a consequence, they do not have a very intuitive design, and it\nis difficult to get a sense of the state of the device just by looking at the\nboot vector. It is better to map all the possible vector states to the swap types (None, Test, Revert)\nvia a set of tables. These tables are reproduced below.\nIn these tables, the \"pending\" and \"confirmed\" fla
gs are shown for illustrative\npurposes; they are not actually present in the boot vector. State I\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Unset | Unset |\n image-ok | Any | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | X | |\n-----------------+--------+-------- \n swap: none |\n----------------------------------- \n\n\nState II\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Any | Good |\n image-ok | Any | N/A |\n-----------------+--------+-------- \n pending | | X |\n confirmed | X | |\n-----------------+--------+-------- \n swap: test |\n----------------------------------- \n\n\nState III\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Uns
et |\n image-ok | 0xff | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | | X |\n-----------------+--------+-------- \n swap: revert (test image running) |\n----------------------------------- \n\n\nState IV\n | slot-0 | slot-1 |\n-----------------+--------+--------|\n magic | Good | Unset |\n image-ok | 0x01 | N/A |\n-----------------+--------+-------- \n pending | | |\n confirmed | X | |\n-----------------+--------+-------- \n swap: none (confirmed test image) |\n-----------------------------------",
"title": "Boot Vector"
},
{
- "location": "/os/modules/bootloader/bootloader/#boot-status",
- "text": "The boot status record allows the boot loader to recover in case it was reset\nwhile in the middle of an image swap operation. Image swapping is discussed\nlater in this document. struct boot_status_table {\n /** * For each field, a value of 0 means any . */ \n uint8_t bst_magic_slot0 ;\n uint8_t bst_magic_scratch ;\n uint8_t bst_copy_done_slot0 ;\n uint8_t bst_status_source ;\n}; struct boot_status {\n uint32_t idx ; /* Which area we re operating on */ \n uint8_t state ; /* Which part of the swapping process are we at */ \n};",
- "title": "Boot Status"
+ "location": "/os/modules/bootloader/bootloader/#high-level-operation",
+ "text": "With the terms defined, we can now explore the boot loader's operation. First,\na high-level overview of the boot process is presented. Then, the following\nsections describe each step of the process in more detail. Procedure: A. Inspect swap status region; is an interrupted swap is being resumed?\n Yes: Complete the partial swap operation; skip to step C.\n No: Proceed to step B. B. Insect boot vector; is a swap requested?\n Yes.\n 1. Is the requested image valid (integrity and security check)?\n Yes.\n a. Perform swap operation.\n b. Persist completion of swap procedure to boot vector.\n c. Proceed to step C.\n No.\n a. Erase invalid image.\n b. Persist failure of swap procedure to boot vector.\n c. Proceed to step C.\n No: Proceed to step C. C. Boot into image in slot 0.",
+ "title": "High-level Operation"
},
{
"location": "/os/modules/bootloader/bootloader/#image-swapping",
- "text": "If the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the process. The two images are swapped according to\nthe following procedure:",
+ "text": "The boot loader swaps the contents of the two image slots for two reasons:\n * User has issued an \"image test\" operation; the image in slot-1 should be\n run once (state II).\n * Test image rebooted without being confirmed; the boot loader should\n revert to the original image currently in slot-1 (state III). If the boot vector indicates that the image in the secondary slot should be\nrun, the boot loader needs to copy it to the primary slot. The image currently\nin the primary slot also needs to be retained in flash so that it can be used\nlater. Furthermore, both images need to be recoverable if the boot loader\nresets in the middle of the swap operation. The two images are swapped\naccording to the following procedure: 1. Determine how many flash sectors each image slot consists of. This\n number must be the same for both slots.\n2. Iterate the list of sector indices in descending order (i.e., starting\n with the greatest index); c
urrent element = index .\n b. Erase scratch area.\n c. Copy slot0[index] to scratch area.\n d. Write updated swap status (i).\n\n e. Erase slot1[index]\n f. Copy slot0[index] to slot1[index]\n - If these are the last sectors (i.e., first swap being perfomed),\n copy the full sector *except* the image trailer.\n - Else, copy entire sector contents.\n g. Write updated swap status (ii).\n\n h. Erase slot0[index].\n i. Copy scratch area slot0[index].\n j. Write updated swap status (iii).\n\n3. 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\ncan be written by the user at a later time. With the image trailer unwritten,\nthe user can test the image in slot 1 (i.e., transition to state II). The particulars of step 3 vary depending on whether an image is being tested or\nreverted:\n * test:\n o Write slot0.copy_done = 1\n (shou
ld now be in state III) * revert:\n o Write slot0.magic = BOOT_MAGIC\n o Write slot0.copy_done = 1\n o Write slot0.image_ok = 1\n (should now be in state IV)",
"title": "Image Swapping"
},
{
- "location": "/os/modules/bootloader/bootloader/#verifying-integrity-of-image",
- "text": "",
- "title": "Verifying integrity of image"
+ "location": "/os/modules/bootloader/bootloader/#swap-status",
+ "text": "The swap status region allows the boot loader to recover in case it restarts in\nthe middle of an image swap operation. The swap status region consists of a\nseries of single-byte records. These records are written independently, and\ntherefore must be padded according to the minimum write size imposed by the\nflash hardware. In the below figure, a min-write-size of 1 is assumed for\nsimplicity. The structure of the swap status region is illustrated below. In\nthis figure, a min-write-size of 1 is assumed for simplicity. 0 1 2 3\n 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\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec127,state 0 |sec127,state 1 |sec127,state 2 |sec126,state 0 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n|sec126,state 1 |sec126,state 2 |sec125,state 0 |sec125,state 1 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-+-+-+-+-+-+-+-+-+-+\n|sec125,state 2 | |\n+-+-+-+-+-+-+-+-+ +\n~ ~\n~ [Records for indices 124 through 1 ~\n~ ~\n~ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+\n~ |sec000,state 0 |sec000,state 1 |sec000,state 2 |\n+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ And now, in English... Each image slot is partitioned into a sequence of flash sectors. If we were to\nenumerate the sectors in a single slot, starting at 0, we would have a list of\nsector indices. Since there are two image slots, each sector index would\ncorrespond to a pair of sectors. For example, sector index 0 corresponds to\nthe first sector in slot 0 and the first sector in slot 1. Furthermore, we\nimpose a limit of 128 in
dices. If an image slot consists of more than 128\nsectors, the flash layout is not compatible with this boot loader. Finally,\nreverse the list of indices such that the list starts with index 127 and ends\nwith 0. The swap status region is a representation of this reversed list. During a swap operation, each sector index transitions through four separate\nstates:\n 0. slot 0: image 0, slot 1: image 1, scratch: N/A\n 1. slot 0: image 0, slot 1: N/A, scratch: image 1 (1- s, erase 1)\n 2. slot 0: N/A, slot 1: image 0, scratch: image 1 (0- 1, erase 0)\n 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\nrecord to the swap status region. Logically, the boot loader only needs one\nrecord per sector index to keep track of the current swap state. However, due\nto limitations imposed by flash hardware, a record cannot be overwritten when\nan index's state chang
es. To solve this problem, the boot loader uses three\nrecords per sector index rather than just one. Each sector-state pair is represented as a set of three records. The record\nvalues map to the above four states as follows | rec0 | rec1 | rec2\n--------+------+------+------\nstate 0 | 0xff | 0xff | 0xff\nstate 1 | 0x01 | 0xff | 0xff\nstate 2 | 0x01 | 0x02 | 0xff\nstate 3 | 0x01 | 0x02 | 0x03 The swap status region can accommodate 128 sector indices. Hence, the size of\nthe region, in bytes, is 128 * min-write-size * 3. The number 128 is chosen\nsomewhat arbitrarily and will likely be made configurable. The only\nrequirement for the index count is that is is great enough to account for a\nmaximum-sized image (i.e., at least as great as the total sector count in an\nimage slot). If a device's image slots use less than 128 sectors, the first\nrecord that gets written will be somewhere in the middle of the region. For\nexample, if a slot uses 64 sectors, the first s
ector index that gets swapped is\n63, which corresponds to the exact halfway point within the region.",
+ "title": "Swap Status"
},
{
"location": "/os/modules/bootloader/bootloader/#reset-recovery",
- "text": "If the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot status file to determine how the image parts are placed in flash. If the boot status file indicates that the images are not contiguous, bootutil\ncompletes the swap operation that was in progress when the system was reset.\nIn other words, it applies the procedure defined in the previous section,\nmoving image 1 into slot 0 and image 0 into slot 1. If the boot status file\nindicates that an image part is present in the scratch area, this part is\ncopied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1. After the swap operation has been completed, the boot loader proceeds as though\nit had just been started.",
+ "text": "If the boot loader resets in the middle of a swap operation, the two images may\nbe discontiguous in flash. Bootutil recovers from this condition by using the\nboot vector to determine how the image parts are distributed in flash. The first step is determine where the relevant swap status region is located.\nBecause this region is embedded within the image slots, its location in flash\nchanges during a swap operation. The below set of tables map boot vector\ncontents to swap status location. In these tables, the \"source\" field\nindicates where the swap status region is located. | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any |\ncopy-done | 0x01 | N/A |\n----------+------------+------------ \nsource: none |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Good | Any
|\ncopy-done | 0xff | N/A |\n----------+------------+------------ \nsource: slot 0 |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Any | Good |\ncopy-done | Any | N/A |\n----------+------------+------------ \nsource: scratch |\n------------------------------------ \n\n | slot-0 | scratch |\n----------+------------+------------|\n magic | Unset | Any |\ncopy-done | 0xff | N/A |\n----------+------------+------------|\nsource: varies |\n------------------------------------+------------------------------+\nThis represents one of two cases: |\no No swaps ever (no status to read, so no harm in checking). |\no Mid-revert; status in slot 0. |\n------------------------------------------
------------------------- If the swap status region indicates that the images are not contiguous,\nbootutil completes the swap operation that was in progress when the system was\nreset. In other words, it applies the procedure defined in the previous\nsection, moving image 1 into slot 0 and image 0 into slot 1. If the boot\nstatus file indicates that an image part is present in the scratch area, this\npart is copied into the correct location by starting at step e or step h in the\narea-swap procedure, depending on whether the part belongs to image 0 or image\n1. After the swap operation has been completed, the boot loader proceeds as though\nit had just been started.",
"title": "Reset Recovery"
},
{
- "location": "/os/modules/bootloader/bootloader/#api",
- "text": "",
- "title": "API"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#example",
- "text": "",
- "title": "Example"
- },
- {
- "location": "/os/modules/bootloader/bootloader/#dependencies",
- "text": "The bootloader depends on the following OS kernel functions: The bootloader does not depend on any flash file system.",
- "title": "Dependencies"
+ "location": "/os/modules/bootloader/bootloader/#integrity-check",
+ "text": "An image is checked for integrity immediately before it gets copied into the\nprimary slot. If the boot loader doesn't perform an image swap, then it\ndoesn't perform an integrity check. During the integrity check, the boot loader verifies the following aspects of\nan image:\n * 32-bit magic number must be correct (0x96f3b83c).\n * Image must contain a SHA256 TLV.\n * Calculated SHA256 must matche SHA256 TLV contents.\n * Image may contain a signature TLV. If it does, its contents must be\n verifiable using a key embedded in the boot loader.",
+ "title": "Integrity Check"
},
{
- "location": "/os/modules/bootloader/bootloader/#list-of-functions",
- "text": "The functions available in bootloader are:",
- "title": "List of Functions"
+ "location": "/os/modules/bootloader/bootloader/#image-signing-and-verification",
+ "text": "As indicated above, the final step of the integrity check is signature\nverification. The boot loader can have one or more public keys embedded in it\nat build time. During signature verification, the boot loader verifies that an\nimage was signed with a private key that corresponds to one of its public keys.\nThe image signature TLV indicates the index of the key that is has been signed\nwith. The boot loader uses this index to identify the corresponding public\nkey. For information on embedding public keys in the boot loader, as well as\nproducing signed images, see: boot/bootutil/signed_images.md",
+ "title": "Image Signing and Verification"
},
{
"location": "/os/modules/bootloader/boot_build_status/",
[3/4] incubator-mynewt-site git commit: Updated bootloader doc
Posted by ad...@apache.org.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/6e429bad/develop/os/modules/bootloader/bootloader/index.html
----------------------------------------------------------------------
diff --git a/develop/os/modules/bootloader/bootloader/index.html b/develop/os/modules/bootloader/bootloader/index.html
index febc09b..4d1064c 100644
--- a/develop/os/modules/bootloader/bootloader/index.html
+++ b/develop/os/modules/bootloader/bootloader/index.html
@@ -527,21 +527,26 @@
</div>
<h1 id="bootloader">Bootloader</h1>
-<p>The "bootloader" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:</p>
+<p>The "bootloader" is the code that loads the Mynewt OS image into memory and conducts some checks before allowing the OS to be run. It manages images for the embedded system and upgrades of those images using protocols over various interfaces (e.g. serial, BLE etc.). Typically, systems with bootloaders have at least two program images coexisting on the same microcontroller, and hence must include branch code that performs a check to see if an attempt to update software is already underway and manage the progress of the process.</p>
+<p>The bootloader in the Apache Mynewt project verifies the cryptographic signature of the firmware image before running it. It maintains a detailed status log for each stage of the boot process. For verification of the authenticity of the OS image, it:</p>
<ul>
<li>Calculates hash of the image.</li>
<li>Uses public key to uncover hash value from included signature. </li>
<li>Compares the calculated and uncovered hashes for a match.</li>
</ul>
<p>The "secure bootloader" should be placed in protected memory on a given microcontroller.</p>
-<p>The Mynewt code is structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an
+<p>The Mynewt bootloader comprises two packages:</p>
+<ul>
+<li>The bootutil library (boot/bootutil)</li>
+<li>The boot application (apps/boot)</li>
+</ul>
+<p>The Mynewt code is thus structured so that the generic bootutil library performs most of the functions of a boot loader. The final step of actually jumping to the main image is kept out of the bootutil library. This last step should instead be implemented in an
architecture-specific project. Boot loader functionality is separated in this
manner for the following two reasons:</p>
<ol>
<li>By keeping architecture-dependent code separate, the bootutil library can be
reused among several boot loaders.</li>
-<li>By excluding the last boot step from the library, the rest of the code can
- be tested in a sim environment.</li>
+<li>By excluding the last boot step from the library, the bootloader can be unit tested since a library can be unit tested but an applicant can't.</li>
</ol>
<h3 id="limitations">Limitations</h3>
<p>The boot loader currently only supports images with the following
@@ -568,7 +573,15 @@ characteristics:</p>
<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">ih_tlv_size</span>; <span style="color: #177500">/* Trailing TLVs */</span>
<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">ih_key_id</span>;
<span style="color: #A90D91">uint8_t</span> <span style="color: #000000">_pad1</span>;
- <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">ih_hdr_size</span>;
+ <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">ih_hdr_s<</span> <span style="color: #000000">bok@bok</span>.<span style="color: #000000">net</span>
+<span style="color: #1C01CE">35</span><span style="color: #000000">d33</span>
+<span style="color: #000000"><</span> <span style="color: #000000">ericmanganaro@gmail</span>.<span style="color: #000000">com</span>
+<span style="color: #1C01CE">42</span><span style="color: #000000">d39</span>
+<span style="color: #000000"><</span> <span style="color: #000000">tam@proxy</span>.<span style="color: #000000">co</span>
+<span style="color: #1C01CE">55</span><span style="color: #000000">d51</span>
+<span style="color: #000000"><</span> <span style="color: #000000">nathan@natb1</span>.<span style="color: #000000">com</span>
+<span style="color: #1C01CE">110</span><span style="color: #000000">d105</span>
+<span style="color: #000000"><</span> <span style="color: #000000">rvs@apache</span>.<span style="color: #000000">orgize</span>;
<span style="color: #A90D91">uint16_t</span> <span style="color: #000000">_pad2</span>;
<span style="color: #A90D91">uint32_t</span> <span style="color: #000000">ih_img_size</span>; <span style="color: #177500">/* Does not include header. */</span>
<span style="color: #A90D91">uint32_t</span> <span style="color: #000000">ih_flags</span>;
@@ -591,8 +604,16 @@ case of changes to the format of the image header.</p>
</pre></div>
-<p>Security data gets added as a footer at the end of the image.</p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/*</span>
+<p>Optional type-length-value records (TLVs) containing image metadata are placed
+after the end of the image. For example, security data gets added as a footer at the end of the image.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #177500">/** Image trailer TLV format. All fields in little endian. */</span>
+<span style="color: #A90D91">struct</span> <span style="color: #000000">image_tlv</span> {
+ <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">it_type</span>; <span style="color: #177500">/* IMAGE_TLV_[...]. */</span>
+ <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">_pad</span>;
+ <span style="color: #A90D91">uint16_t</span> <span style="color: #000000">it_len</span> <span style="color: #177500">/* Data length (not including TLV header). */</span>
+};
+
+<span style="color: #177500">/*</span>
<span style="color: #177500"> * Image trailer TLV types.</span>
<span style="color: #177500"> */</span>
<span style="color: #633820">#define IMAGE_TLV_SHA256 1 </span><span style="color: #177500">/* SHA256 of image hdr and body */</span><span style="color: #633820"></span>
@@ -601,13 +622,23 @@ case of changes to the format of the image header.</p>
</pre></div>
-<h3 id="flash-areas">Flash Areas</h3>
-<p>Bootutil uses the same concept of "flash areas" as the nffs file system.
-Briefly, an 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.</p>
-<p>The areas used for image data must not be used for anything else. In
-particular, these areas must be kept separate from the nffs file system.</p>
+<h3 id="flash-map">Flash Map</h3>
+<p>A Mynewt device's flash is partitioned according to its <em>flash map</em>. At a high
+level, the flash map maps numeric IDs to <em>flash areas</em>. A flash area is a
+region of disk with the following properties:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">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.
+</pre></div>
+
+
+<p>The boot loader uses the following flash areas:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #633820">#define FLASH_AREA_BOOTLOADER 0</span>
+<span style="color: #633820">#define FLASH_AREA_IMAGE_0 1</span>
+<span style="color: #633820">#define FLASH_AREA_IMAGE_1 2</span>
+<span style="color: #633820">#define FLASH_AREA_IMAGE_SCRATCH 3</span>
+</pre></div>
+
+
<h3 id="image-slots">Image Slots</h3>
<p>A portion of the flash memory is partitioned into two image slots: a primary
slot and a secondary slot. The boot loader will only run an image from the
@@ -616,65 +647,398 @@ 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.</p>
<p>In addition to the two image slots, the boot loader requires a scratch area to
allow for reliable image swapping.</p>
-<p>All areas used by image data (including the scratch area) must be the same
-size.</p>
+<h3 id="boot-states">Boot States</h3>
+<p>Logically, you can think of a pair of flags associated with each image slot:
+pending and confirmed. On startup, the boot loader determines the state of the
+device by inspecting each pair of flags. These flags have the following
+meanings:</p>
+<ul>
+<li>pending: image gets tested on next reboot; absent subsequent confirm command,
+ revert to original image on second reboot.</li>
+<li>confirmed: always use image unless excluded by a test image.</li>
+</ul>
+<p>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. This is 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.</p>
+<p>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.</p>
+<p>The following set of tables illustrate the three possible states that the
+device can be in:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> | slot-0 | slot-1 |
+---------------+--------+--------|
+ pending | | |
+ confirmed | X | |
+---------------+--------+--------'
+Image 0 confirmed; |
+No change on reboot |
+---------------------------------'
+
+ | slot-0 | slot-1 |
+---------------+--------+--------|
+ pending | | X |
+ confirmed | X | |
+---------------+--------+--------'
+Image 0 confirmed; |
+Test image 1 on next reboot |
+---------------------------------'
+
+ | slot-0 | slot-1 |
+---------------+--------+--------|
+ pending | | |
+ confirmed | | X |
+---------------+--------+--------'
+Testing image 0; |
+Revert to image 1 on next reboot |
+---------------------------------'
+</pre></div>
+
+
<h3 id="boot-vector">Boot Vector</h3>
-<p>If a vector file contains a version which doesn't correspond to an image
-actually present in flash, the boot loader deletes the file and procedes as
-though the file was not present.</p>
-<h3 id="boot-status">Boot Status</h3>
-<p>The boot status record allows the boot loader to recover in case it was reset
-while in the middle of an image swap operation. Image swapping is discussed
-later in this document. </p>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">boot_status_table</span> {
- <span style="color: #177500">/**</span>
-<span style="color: #177500"> * For each field, a value of 0 means "any".</span>
-<span style="color: #177500"> */</span>
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_magic_slot0</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_magic_scratch</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_copy_done_slot0</span>;
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">bst_status_source</span>;
-};
+<p>At startup, the boot loader determines which of the above three boot states a device is in by inspecting the boot vector. The boot vector consists of two
+records (called "image trailers"), one written at the end of each image slot.
+An image trailer has the following structure:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> 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
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~ MAGIC (16 octets) ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+~ ~
+~ Swap status (128 * min-write-size * 3) ~
+~ ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Copy done | 0xff padding (up to min-write-sz - 1) ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+| Image OK | 0xff padding (up to min-write-sz - 1) ~
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</pre></div>
-<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"><span style="color: #A90D91">struct</span> <span style="color: #000000">boot_status</span> {
- <span style="color: #A90D91">uint32_t</span> <span style="color: #000000">idx</span>; <span style="color: #177500">/* Which area we're operating on */</span>
- <span style="color: #A90D91">uint8_t</span> <span style="color: #000000">state</span>; <span style="color: #177500">/* Which part of the swapping process are we at */</span>
-};
+<p>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.</p>
+<p>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.</p>
+<p>The fields are defined as follows:</p>
+<ol>
+<li>
+<p>MAGIC: The following 16 bytes, written in host-byte-order:</p>
+<p>const uint32_t boot_img_magic[4] = {
+ 0xf395c277,
+ 0x7fefd260,
+ 0x0f505235,
+ 0x8079b62c,
+};</p>
+</li>
+<li>
+<p>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.</p>
+</li>
+<li>
+<p>Copy done: A single byte indicating whether the image in this slot is
+complete (0x01=d< bok@bok.net
+35d33
+< ericmanganaro@gmail.com
+42d39
+< tam@proxy.co
+55d51
+< nathan@natb1.com
+110d105
+< rvs@apache.orgone; 0xff=not done).</p>
+</li>
+<li>
+<p>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).</p>
+</li>
+</ol>
+<p>The boot vector 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
+boot vector. It is better to map all the possible vector states to the swap types (None, Test, Revert)
+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 boot vector.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">State I
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Unset | Unset |
+ image-ok | Any | N/A |
+-----------------+--------+--------'
+ pending | | |
+ confirmed | X | |
+-----------------+--------+--------'
+ swap: none |
+-----------------------------------'
+
+
+State II
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Any | Good |
+ image-ok | Any | N/A |
+-----------------+--------+--------'
+ pending | | X |
+ confirmed | X | |
+-----------------+--------+--------'
+ swap: test |
+-----------------------------------'
+
+
+State III
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Good | Unset |
+ image-ok | 0xff | N/A |
+-----------------+--------+--------'
+ pending | | |
+ confirmed | | X |
+-----------------+--------+--------'
+ swap: revert (test image running) |
+-----------------------------------'
+
+
+State IV
+ | slot-0 | slot-1 |
+-----------------+--------+--------|
+ magic | Good | Unset |
+ image-ok | 0x01 | N/A |
+-----------------+--------+--------'
+ pending | | |
+ confirmed | X | |
+-----------------+--------+--------'
+ swap: none (confirmed test image) |
+-----------------------------------'
</pre></div>
+<h3 id="high-level-operation">High-level Operation</h3>
+<p>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.</p>
+<p>Procedure:</p>
+<p>A. Inspect swap status region; is an interrupted swap is being resumed?
+ Yes: Complete the partial swap operation; skip to step C.
+ No: Proceed to step B.</p>
+<p>B. Insect boot vector; 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 boot vector.
+ c. Proceed to step C.
+ No.
+ a. Erase invalid image.
+ b. Persist failure of swap procedure to boot vector.
+ c. Proceed to step C.
+ No: Proceed to step C.</p>
+<p>C. Boot into image in slot 0.</p>
<h3 id="image-swapping">Image Swapping</h3>
+<p>The boot loader swaps the contents of the two image slots for two reasons:
+ * User has issued an "image test" operation; the image in slot-1 should be
+ run once (state II).
+ * Test image rebooted without being confirmed; the boot loader should
+ revert to the original image currently in slot-1 (state III).</p>
<p>If the boot vector 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 process. The two images are swapped according to
-the following procedure:</p>
-<h3 id="verifying-integrity-of-image">Verifying integrity of image</h3>
+resets in the middle of the swap operation. The two images are swapped
+according to the following procedure:</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">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.
+ 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].
+ j. Write updated swap status (iii).
+
+3. Persist completion of swap procedure to slot 0 image trailer.
+</pre></div>
+
+
+<p>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).</p>
+<p>The particulars of step 3 vary depending on whether an image is being tested or
+reverted:
+ * test:
+ o Write slot0.copy_done = 1
+ (should now be in state III)</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%">* revert:
+ o Write slot0.magic = BOOT_MAGIC
+ o Write slot0.copy_done = 1
+ o Write slot0.image_ok = 1
+ (should now be in state IV)
+</pre></div>
+
+
+<h3 id="swap-status">Swap Status</h3>
+<p>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.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> 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 |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+</pre></div>
+
+
+<p>And now, in English...</p>
+<p>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.</p>
+<p>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)</p>
+<p>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.</p>
+<p>Each sector-state pair is represented as a set of three records. The record
+values map to the above four states as follows</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> | rec0 | rec1 | rec2
+--------+------+------+------
+state 0 | 0xff | 0xff | 0xff
+state 1 | 0x01 | 0xff | 0xff
+state 2 | 0x01 | 0x02 | 0xff
+state 3 | 0x01 | 0x02 | 0x03
+</pre></div>
+
+
+<p>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.</p>
<h3 id="reset-recovery">Reset Recovery</h3>
<p>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
-boot status file to determine how the image parts are placed in flash.</p>
-<p>If the boot status file 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
+boot vector to determine how the image parts are distributed in flash.</p>
+<p>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 boot vector
+contents to swap status location. In these tables, the "source" field
+indicates where the swap status region is located.</p>
+<div class="codehilite" style="background: #ffffff"><pre style="line-height: 125%"> | 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: varies |
+------------------------------------+------------------------------+
+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. |
+-------------------------------------------------------------------'
+</pre></div>
+
+
+<p>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.</p>
<p>After the swap operation has been completed, the boot loader proceeds as though
it had just been started.</p>
-<h3 id="api">API</h3>
-<h3 id="example">Example</h3>
-<h3 id="dependencies">Dependencies</h3>
-<p>The bootloader depends on the following OS kernel functions:</p>
-<p>The bootloader does not depend on any flash file system.</p>
-<h3 id="list-of-functions">List of Functions</h3>
-<p><Comments such as these instructions are placed within angle brackets. List all the functions here. Note how the anchors work. You put the text you want to show up as a link within [] and the relevant #heading within (). Note that the header has to have at least 2 words for the anchor to work - that's how it is. "no-highlight" disables syntax highlighting. You can enable it for a particular language by specifying what the language is instead of "no-highlight". Be warned that this highlighting or no-highlighting specification may not show up nicely on Mou.></p>
-<p>The functions available in bootloader are:</p>
+<h3 id="integrity-check">Integrity Check</h3>
+<p>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
+doesn't perform an integrity check.</p>
+<p>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 matche SHA256 TLV contents.
+ * Image <em>may</em> contain a signature TLV. If it does, its contents must be
+ verifiable using a key embedded in the boot loader.</p>
+<h3 id="image-signing-and-verification">Image Signing and Verification</h3>
+<p>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.</p>
+<p>For information on embedding public keys in the boot loader, as well as
+producing signed images, see: boot/bootutil/signed_images.md </p>
<div class="row">