Docs: Adding Block-based OTAs and verified boot to index, nav
Bug: 17884100
Change-Id: I40576dc7c5dbf058f8798d060975fac425d408bc
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index ebb8d8b..05a51d3 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -315,6 +315,7 @@
</div>
<ul>
<li><a href="<?cs var:toroot ?>devices/tech/security/secureboot/verified-boot.html">Verified boot</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/security/secureboot/block-ota.html">Block-based OTA</a></li>
</ul>
</li>
<li class="nav-section">
diff --git a/src/devices/tech/security/secureboot/block-ota.jd b/src/devices/tech/security/secureboot/block-ota.jd
new file mode 100755
index 0000000..5f93608
--- /dev/null
+++ b/src/devices/tech/security/secureboot/block-ota.jd
@@ -0,0 +1,77 @@
+page.title=Block-Based OTAs
+@jd:body
+
+<!--
+ Copyright 2014 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+ </div>
+</div>
+
+<h2 id="introduction">Introduction</h2>
+
+<p>You can enable block-based over-the-air (OTA) updates for new devices running Android 5.0. OTA is the mechanism by which OEMs remotely update the system partition of a device:</p>
+<ul>
+<li><b>Android 4.4</b> and earlier versions used file OTA updates, which ensured that devices contained similar file contents, permissions, and modes, but allowed metadata such as timestamps and the layout of the underlying storage to vary between devices based on the update method.</li>
+<li><b>Android 5.0</b> and later versions use block OTA updates to ensure that each device uses the exact same partition. Instead of comparing individual files and computing binary patches, block OTA handles the entire partition as one file and computes a single binary patch, ensuring the resultant partition contains exactly the intended bits. This allows the device system image to achieve the same state via fastboot or OTA.</li>
+</ul>
+<p>Because block OTA ensures that each device uses the same partition, it enables the use of dm-verity to cryptographically sign the system partition. For details on dm-verity, see <a
+href="{@docRoot}devices/tech/security/dm-verity.html">Using dm-verity</a>.</p>
+
+<p class="note"><strong>Note:</strong> You must have a working block OTA system before using dm-verity.</p>
+
+<h2 id="Recommendations">Recommendations</h2>
+
+<p>For devices that launched with Android 4.4 or earlier, use file OTA updates. While is it possible to transition devices by sending a full block OTA of Android 5.0 or later, it requires extensive modifications to the bootloader and the update size is large (block OTA downloads are approximately 20% larger than file OTA downloads).</p>
+<p>For devices launching with Android 5.0 or later, use block OTA updates. New devices shipping with Android 5.0 or later include support for block OTA updates. To generate a block-based OTA, pass the "--block" option to ota_from_target_files.</p>
+<p>Because dm-verity requires bootloader support found only in new devices shipping with Android 5.0 or later, you <i>cannot</i> enable dm-verity for existing devices.</p>
+
+<h2 id="File vs. Block OTAs">File vs. Block OTAs</h2>
+
+<p>During a file-based OTA, Android attempts to change the contents of the system partition at the filesystem layer (on a file-by-file basis). The update is not guaranteed to write files in a consistent order, have a consistent last modified time or superblock, or even place the blocks in the same location on the block device. For this reason, file-based OTAs fail on a dm-verity-enabled device; after the OTA attempt, the device does not boot.</p>
+<p>During a block-based OTA, Android serves the device the difference between the two block images (rather than two sets of files). The update checks a device build against the corresponding build server at the block level (below the filesystem) using one of the following methods:</p>
+<ul>
+<li><b>Full update</b>. Copying the full system image is simple and makes patch generation easy, but also generates large images that can make applying patches expensive.</li>
+<li><b>Incremental update</b>. Using a binary differ tool generates smaller images and makes patch application easy, but is memory-intensive when generating the patch itself.</li>
+</ul>
+
+<p class="note"><strong>Note:</strong> adb fastboot places the exact same bits on the device as a full OTA, so flashing is compatible with block OTA.</p>
+
+<h3 id="Unmodified Systems">Updating Unmodified Systems</h3>
+
+<p>For devices with <i>unmodified</i> system partitions running Android 5.0, the download and install process for a block OTA remains the same as for a file OTA. However, the OTA update itself might include one or more of the following differences:</p>
+<ul>
+<li><b>Increased download size</b>. Full block OTA updates are approximately the same size as full file OTA updates. However, big incremental updates can be 10-20% larger while small incremental updates (i.e. many DM verity checksum changes but few file changes) can be just a few megabytes larger. In general, incremental block OTA updates are larger than incremental file OTA updates due to:
+<ul>
+<li><i>Data preservation</i>. Block-based OTAs preserve more data (file metadata, dm-verity data, ext4 layout, etc.) than file-based OTA.</li>
+<li><i>Binary patch tool differences</i>. File-based OTAs use bsdiff, which is not feasible to run on large files (such as an entire system image). Instead, block-based OTAs use xdelta3, which is faster and requires less memory to process large files, but creates larger patches than bsdiff.</li>
+<li><i>Compression capabilities</i>. When patching some file types (.zip, .apk, .jar, .gz), a file OTA update decompresses the file and computes a patch for the uncompressed data, recompressing it after patching. This can produce substantially smaller patches than a binary patch on compressed data. Block OTA updates do not support file decompression and recompression.</li>
+<li><i>Computation algorithm differences</i>. In a file OTA update, if a file path is identical in both builds, the OTA package contains no data for that file. In a block OTA update, determining little or no change in a file depends on the quality of the patch computation algorithm and layout of file data in both source and target system. For example, images.xdelta3 can locate data similarities only between nearby locations; varying the nearby parameter affects the memory and time required to compute and apply the patch.</li>
+</ul>
+</li>
+<li><b>Sensitivity to faulty flash and RAM</b>. If a file is corrupted, a file OTA succeeds as long as it doesn't touch the corrupted file, but a block OTA fails if it detects any corruption on the system partition.</li>
+</ul>
+
+<h3 id="Modified Systems">Updating Modified Systems</h3>
+<p>For devices with <i>modified</i> system partitions running Android 5.0:</p>
+<ul>
+<li><b>Incremental block OTA updates fail</b>. A system partition might be modified during an adb remount or as a result of malware. File OTA tolerates some changes to the partition, such the addition of files that are not part of the source or target build. However, block OTA does not tolerate additions to the partition, so users will need to install a full OTA (overwriting any system partition modifications) or flash a new system image to enable future OTAs.</li>
+<li><b>Attempts to change modified files cause update failure</b>. For both file and block OTA updates, if the OTA attempts to change a file that has been modified, the OTA update fails.</li>
+<li><b>Attempts to access modified files generate errors </b><i>(dm-verity only)</i>. For both file and block OTA updates, if dm-verity is enabled and the OTA attempts to access modified parts of the system filesystem, the OTA generates an error.</li>
+</ul>
\ No newline at end of file
diff --git a/src/devices/tech/security/secureboot/index.jd b/src/devices/tech/security/secureboot/index.jd
index d507677..8555602 100644
--- a/src/devices/tech/security/secureboot/index.jd
+++ b/src/devices/tech/security/secureboot/index.jd
@@ -2,7 +2,7 @@
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -26,7 +26,7 @@
<h2 id="introduction">Introduction</h2>
-<p>Android 4.4 supports verified boot through the optional device-mapper-verity
+<p>Android 4.4 and later supports verified boot through the optional device-mapper-verity
(dm-verity) kernel feature, which provides transparent integrity checking of
block devices. dm-verity helps prevent persistent rootkits that can hold onto
root privileges and compromise devices. This experimental feature helps Android
@@ -63,9 +63,9 @@
<p>Manufacturers use that key to verify the signature on the first-level
bootloader, which in turn verifies the signature on subsequent levels, the
application bootloader and eventually the kernel. Each manufacturer wishing to
-take advantage of verified boot should have a method for verifying the integrity
-of the kernel. Assuming the kernel has been verified, the kernel can look at a
-block device and verify it as it is mounted.</p>
+take advantage of <a href="verified-boot.html">verified boot</a> should have a
+method for verifying the integrity of the kernel. Assuming the kernel has been
+verified, the kernel can look at a block device and verify it as it is mounted.</p>
<p>One way of verifying a block device is to directly hash its contents and compare
them to a stored value. However, attempting to verify an entire block device can
@@ -88,35 +88,14 @@
<h2 id="prerequisites">Prerequisites</h2>
+<h3 id="verified-boot">Establishing a verified boot flow</h3>
+<p>To greatly reduce the risk of compromise, verify the kernel using a key
+burned into the device. For details, see <a href="verified-boot.jd">Verified boot</a>.</p>
+
<h3 id="block-otas">Switching to block-oriented OTAs</h3>
-
-<p>To enable dm-verity on your devices, you <strong>must</strong> move from file-based "over the
-air" (OTA) updates to block-oriented OTAs. This is needed because during OTA,
-Android attempts to change the contents of the system partition at the
-filesystem layer.<br/>
-And since OTA works on a file-by-file basis, it is not guaranteed to write files
-in a consistent order, have a consistent last modified time or superblock, or
-even place the blocks in the same location on the block device. For this reason,
-<em>file-based OTAs will fail on a dm-verity-enabled device.</em><strong>The device will
-not boot after OTA.</strong></p>
-
-<p>So you must use block-oriented OTAs. With block-oriented OTAs, you serve the
-device the difference between the two block images rather than the two sets of
-files. Many manufacturers have already moved to block-oriented OTAs to make them
-more reproducible and predictable.</p>
-
-<p>A block-oriented OTA checks a device build against the corresponding build
-server at the block device level, below the filesystem. This can be done in a
-couple of different ways, each with their own benefits and drawbacks:</p>
-
-<ul>
-<li><em>Copy the full system image to the device</em> - This is simple and makes patch
-generation easy. But it also makes the application of those patches quite
-expensive as the resulting images are large.</li>
-<li><em>Employ a binary differ</em> - These tools, such as <code>bsdiff</code>, simplify patch
-application as images are much smaller. But these tools tend to be memory
-intensive and therefore expensive in generating the patches themselves.</li>
-</ul>
+<p>To enable dm-verity for a device, you must use block-based over-the-air
+(OTA) updates to ensure all devices use the same system partition. For details,
+see <a href="block-ota.html">Block-Based OTAs</a>.</p>
<h3 id="config-dm-verity">Configuring dm-verity</h3>
@@ -308,7 +287,9 @@
<h2 id="supporting-docs">Supporting documentation</h2>
-<p><a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup - dm-verity: device-mapper block integrity checking
+<p><a href="verified-boot.html">Verified boot</a><br/>
+<a href="block-ota.html"></a><br/>
+<a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup - dm-verity: device-mapper block integrity checking
target</a><br/>
<a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The Chromium Projects - Verified
Boot</a><br/>