Merge "Docs: Adding docs for Camera V3 HAL. Bug: 9481917"
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 82df2d2..2ca4c5a 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -128,6 +128,11 @@
</a>
</li>
<li>
+ <a href="<?cs var:toroot ?>devices/tech/security/dm-verity.html">
+ <span class="en">dm-verity on boot</span>
+ </a>
+ </li>
+ <li>
<a href="<?cs var:toroot ?>devices/tech/security/se-linux.html">
<span class="en">Security-Enhanced Linux</span>
</a>
@@ -158,6 +163,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/dalvik-bytecode.html">Bytecode Format</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/dex-format.html">.Dex Format</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/instruction-formats.html">Instruction Formats</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/dalvik/art.html">Introducing ART</a></li>
</ul>
</li>
diff --git a/src/devices/low-ram.jd b/src/devices/low-ram.jd
index efa6377..711fadc 100644
--- a/src/devices/low-ram.jd
+++ b/src/devices/low-ram.jd
@@ -227,9 +227,9 @@
<li>By default, the Linux kernel swaps in 8 pages of memory at a time. When
using ZRAM, the incremental cost of reading 1 page at a time is negligible
and may help in case the device is under extreme memory pressure. To read
- only 1 page at a time, add the following to your init.rc:<br/>
+ only 1 page at a time, add the following to your init.rc:<br />
`write /proc/sys/vm/page-cluster 0`</li>
- <li>In your init.rc, after the `mount_all /fstab.X` line, add:<br/>
+ <li>In your init.rc, after the `mount_all /fstab.X` line, add:<br />
`swapon_all /fstab.X`</li>
<li>The memory cgroups are automatically configured at boot time if the
feature is enabled in kernel.</li>
diff --git a/src/devices/tech/dalvik/art.jd b/src/devices/tech/dalvik/art.jd
new file mode 100644
index 0000000..dd3c6f6
--- /dev/null
+++ b/src/devices/tech/dalvik/art.jd
@@ -0,0 +1,52 @@
+page.title=Introducing ART
+@jd:body
+
+<!--
+ Copyright 2013 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.
+-->
+<p>
+ART is a new Android runtime being introduced experimentally in the 4.4
+release. This is a preview of work in progress in KitKat that can be turned on
+in Settings > developer options. This is available for the purpose of
+obtaining early developer and partner feedback.</p>
+
+<p><strong>Important</strong>: Dalvik must remain the default runtime or
+you risk breaking your Android implementations and third-party applications.</p>
+
+<p>
+Two runtimes are now available, the existing Dalvik runtime (libdvm.so) and the
+ART (libart.so). A device can be built using either or both.
+(You can dual boot from Developer options if both are installed.)
+</p>
+
+<p>
+The <code>dalvikvm</code> command line tool can run with either of them now.
+See runtime_common.mk. That is included from build/target/product/runtime_libdvm.mk or
+build/target/product/runtime_libdvm.mk or both.</p>
+
+<p>
+A new <code>PRODUCT_RUNTIMES</code> variable controls which runtimes
+are included in a build. Include it within either
+build/target/product/core_minimal.mk or build/target/product/core_base.mk.
+</p>
+
+<p>
+Add this to the device makefile to have both runtimes
+built and installed, with Dalvik as the default:
+</br>
+<code>PRODUCT_RUNTIMES := runtime_libdvm_default</code>
+</br>
+<code>PRODUCT_RUNTIMES += runtime_libart</code>
+</p>
diff --git a/src/devices/tech/dalvik/index.jd b/src/devices/tech/dalvik/index.jd
index ed36231..7bc11bb 100644
--- a/src/devices/tech/dalvik/index.jd
+++ b/src/devices/tech/dalvik/index.jd
@@ -22,4 +22,8 @@
<p>Much of the documentation in this directory is intended to help
with the ongoing development of Dalvik, as opposed to most of the
other documentation on this site, which is geared more towards
-application development.</p>
\ No newline at end of file
+application development.</p>
+
+<p>Please note, in Android 4.4 a new virtual machine - ART - is being introduced
+experimentally that will eventually replace Dalvik. Please see <a
+href="{@docRoot}devices/tech/dalvik/art.html">Introducing ART</a> for details.
diff --git a/src/devices/tech/security/dm-verity.jd b/src/devices/tech/security/dm-verity.jd
new file mode 100644
index 0000000..79e375f
--- /dev/null
+++ b/src/devices/tech/security/dm-verity.jd
@@ -0,0 +1,318 @@
+page.title=dm-verity on boot
+@jd:body
+
+<!--
+ Copyright 2010 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>Android 4.4 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
+users be sure when booting a device it is in the same state as when it was last
+used.</p>
+
+<p>Clever malware with root privileges can hide from detection programs and
+otherwise mask themselves. The rooting software can do this because it is often
+more privileged than the detectors, enabling the software to "lie" to to the
+detection programs.</p>
+
+<p>The dm-verity feature lets you look at a block device, the underlying storage
+layer of the file system, and determine if it matches its expected
+configuration. It does this using a cryptographic hash tree. For every block
+(typically 4k), there is a SHA256 hash.</p>
+
+<p>And since the hash values are stored in a tree of pages, only the top-level
+"root" hash must be trusted to verify the rest of the tree. The ability to
+modify any of the blocks would be equivalent to breaking the cryptographic hash.
+See the following diagram for a depiction of this structure.</p>
+
+<p><img src="images/dm-verity-hash-table.png" alt="dm-verity-hash-table"/><br/>
+A public key is included on the boot partition, which must be verified
+externally by the OEM. That key is used to verify the signature for that hash
+and confirm the device's system partition is protected and unchanged.</p>
+
+<h2 id="operation">Operation</h2>
+
+<p>dm-verity protection lives in the kernel. So if rooting software compromises the
+system before the kernel comes up, it will retain that access. To mitigate this
+risk, most manufacturers verify the kernel using a key burned into the device.
+That key is not changeable once the device leaves the factory.</p>
+
+<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>
+
+<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
+take an extended period and consume much of a device's power. Devices would take
+long periods to boot and then be significantly drained prior to use.</p>
+
+<p>Instead, dm-verity verifies blocks individually and only when each one is
+accessed. When read into memory, the block is hashed in parallel. The hash is
+then verified up the tree. And since reading the block is such an expensive
+operation, the latency introduced by this block-level verification is
+comparatively nominal.</p>
+
+<p>If verification fails, the device generates an I/O error indicating the block
+cannot be read. It will appear as if the filesystem has been corrupted, as is
+expected.</p>
+
+<p>Applications may choose to proceed without the resulting data, such as when
+those results are not required to the application's primary function. However,
+if the application cannot continue without the data, it will fail.</p>
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<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>
+
+<h3 id="config-dm-verity">Configuring dm-verity</h3>
+
+<p>After switching to block-oriented OTAs, incorporate the latest Android kernel or
+use a stock upstream kernel and enable dm-verity support by including the
+relevant configuration option:<br/>
+<code>CONFIG_DM_VERITY
+</code></p>
+<p>When using the Android kernel, dm-verity is turned on when the kernel is built.</p>
+
+<h2 id="implementation">Implementation</h2>
+
+<h3 id="summary">Summary</h3>
+
+<ol>
+<li>Generate an ext4 system image.</li>
+<li><a href="#heading=h.wiiuowe37q8h">Generate a hash tree</a> for that image.</li>
+<li><a href="#heading=h.cw7mesnrerea">Build a dm-verity table</a> for that hash tree.</li>
+<li><a href="#heading=h.maq6jfk4vx92">Sign that dm-verity table</a> to produce a table
+signature.</li>
+<li><a href="#heading=h.tkceh5wnx7z2">Bundle the table signature</a> and dm-verity table
+into verity metadata.</li>
+<li>Concatenate the system image, the verity metadata, and the hash tree.</li>
+</ol>
+
+<p>See the <a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The Chromium Projects - Verified
+Boot</a>
+for a detailed description of the hash tree and dm-verity table.</p>
+
+<h3 id="hash-tree">Generating the hash tree</h3>
+
+<p>As described in the <a href="#heading=h.q4z3ftrhbehy">Introduction</a>, the hash tree is
+integral to dm-verity. The
+<a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup</a> tool will
+generate a hash tree for you. Alternatively, a compatible one is defined here:</p>
+
+<pre>
+<your block device name> <your block device name> <block size> <block size> <image size in blocks> <image size in blocks + 8> <root hash> <salt>
+</pre>
+
+<p>To form the hash, the system image is split at layer 0 into 4k blocks, each
+assigned a SHA256 hash. Layer 1 is formed by joining only those SHA256 hashes
+into 4k blocks, resulting in a much smaller image. Layer 2 is formed
+identically, with the SHA256 hashes of Layer 1.</p>
+
+<p>This is done until the SHA256 hashes of the previous layer can fit in a single
+block. When get the SHA256 of that block, you have the root hash of the tree. </p>
+
+<p>The size of the hash tree (and corresponding disk space usage) varies with the
+size of the verified partition. In practice, the size of hash trees tends to be
+small, often less than 30 MB.</p>
+
+<p>If you have a block in a layer that isn't completely filled naturally by the
+hashes of the previous layer, you should pad it with zeroes to achieve the
+expected 4k. This allows you to know the hash tree hasn't been removed and is
+instead completed with blank data.</p>
+
+<p>To generate the hash tree, concatenate the layer 2 hashes onto those for layer
+1, the layer 3 the hashes onto those of layer 2, and so on. Write all of this
+out to disk. Note that this doesn't reference layer 0 of the root hash.</p>
+
+<p>To recap, the general algorithm to construct the hash tree is as follows:</p>
+
+<ol>
+<li>Choose a random salt (hexadecimal encoding).</li>
+<li>Unsparse your system image into 4k blocks.</li>
+<li>For each block, get its (salted) SHA256 hash.</li>
+<li>Concatenate these hashes to form a level</li>
+<li>Pad the level with 0s to a 4k block boundary.</li>
+<li>Concatenate the level to your hash tree.</li>
+<li>Repeat steps 2-6 using the previous level as the source for the next until
+you have only a single hash.</li>
+</ol>
+
+<p>The result of this is a single hash, which is your root hash. This and your salt
+are used during the construction of your dm-verity mapping hash table.</p>
+
+<h3 id="mapping-table">Building the dm-verity mapping table</h3>
+
+<p>Build the dm-verity mapping table, which identifies the block device (or target)
+for the kernel and the location of the hash tree (which is the same value.) This
+mapping is used for <code>fstab</code> generation and booting. The table also identifies
+the size of the blocks and the hash_start, or the offset in hash size blocks
+(length of layer 0).</p>
+
+<p>See <a href="https://code.google.com/p/cryptsetup/wiki/DMVerity">cryptsetup</a> for a
+detailed description of the verity target mapping table fields.</p>
+
+<h3 id="signing">Signing the dm-verity table</h3>
+
+<p>Sign the dm-verity table to produce a table signature. When verifying a
+partition, the table signature is validated first. This is done against a key on
+your boot image in a fixed location. Keys are typically included in the
+manufacturers' build systems for automatic inclusion on devices in a fixed
+location.</p>
+
+<p>To verify the partition with this signature and key combination:</p>
+
+<ol>
+<li>Add an RSA-2048 key in libmincrypt-compatible format to the /boot partition
+at /verity_key. Identify the location of the key used to verify the hash
+tree.</li>
+<li>In the fstab for the relevant entry, add 'verify' to the fs_mgr flags.</li>
+</ol>
+
+<h3 id="metadata">Bundling the table signature into metadata</h3>
+
+<p>Bundle the table signature and dm-verity table into verity metadata. The entire
+block of metadata is versioned so it may be extended, such as to add a second
+kind of signature or change some ordering.</p>
+
+<p>As a sanity check, a magic number is associated with each set of table metadata
+that helps identify the table. Since the length is included in the ext4 system
+image header, this provides a way to search for the metadata without knowing the
+contents of the data itself.</p>
+
+<p>This makes sure you haven't elected to verify an unverified partition. If so,
+the absence of this magic number will halt the verification process. This number
+resembles:<br/>
+0xb001b001</p>
+
+<p>The byte values in hex are:</p>
+
+<ul>
+<li>first byte = b0</li>
+<li>second byte = 01</li>
+<li>third byte = b0</li>
+<li>fourth byte = 01</li>
+</ul>
+
+<p>The following diagram depicts the breakdown of the verity metadata:</p>
+
+<pre><magic number>|<version>|<signature>|<table length>|<table>|<padding>
+\-------------------------------------------------------------------/
+\----------------------------------------------------------/ |
+ | |
+ | 32K
+ block content
+</pre>
+
+<p>And this table describes those metadata fields.</p>
+
+<table>
+<tr>
+<th>Field</th>
+<th>Purpose</th>
+<th>Size</th>
+<th>Value</th>
+</tr>
+<tr>
+<td>magic number</td>
+<td>used by fs_mgr as a sanity check</td>
+<td>4 bytes</td>
+<td>0xb001b001</td>
+</tr>
+<tr>
+<td>version</td>
+<td>used to version the metadata block</td>
+<td>4 bytes</td>
+<td>currently 0</td>
+</tr>
+<tr>
+<td>signature</td>
+<td>the signature of the table in PKCS1.5 padded form</td>
+<td>256 bytes</td>
+<td></td>
+</tr>
+<tr>
+<td>table length</td>
+<td>the length of the dm-verity table in bytes</td>
+<td>4 bytes</td>
+<td></td>
+</tr>
+<tr>
+<td>table</td>
+<td>the dm-verity table described earlier</td>
+<td>`table length` bytes</td>
+<td></td>
+</tr>
+<tr>
+<td>padding</td>
+<td>this structure is 0-padded to 32k in length</td>
+<td></td>
+<td>0</td>
+</tr>
+</table>
+
+<p>For additional assistance, contact
+<a href="mailto:gcondra@google.com">gcondra@google.com</a>.</p>
+
+<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
+target</a><br/>
+<a href="http://www.chromium.org/chromium-os/chromiumos-design-docs/verified-boot">The Chromium Projects - Verified
+Boot</a><br/>
+<a
+href="http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/device-mapper/verity.txt">Linux Kernel Documentation:
+verity.txt</a></p>
diff --git a/src/devices/tech/security/images/dm-verity-hash-table.png b/src/devices/tech/security/images/dm-verity-hash-table.png
new file mode 100644
index 0000000..3761dc6
--- /dev/null
+++ b/src/devices/tech/security/images/dm-verity-hash-table.png
Binary files differ
diff --git a/src/devices/tech/security/index.jd b/src/devices/tech/security/index.jd
index 2c0186c..e53895a 100644
--- a/src/devices/tech/security/index.jd
+++ b/src/devices/tech/security/index.jd
@@ -16,6 +16,13 @@
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>Android is a modern mobile platform that was designed to be truly open. Android
@@ -273,6 +280,14 @@
applications, files created by one application cannot be read or altered by
another application.</p>
+<h2 id="se-linux">Security-Enhanced Linux</h2>
+
+<p>Android uses Security-Enhanced
+Linux (SELinux) to apply access control policies and establish an environment of
+mandatory access control (mac). See <a
+href="{@docRoot}devices/tech/security/se-linux.html">Validating
+Security-Enhanced Linux in
+Android</a> for details.</p>
<h2 id="crypto">Cryptography</h2>
diff --git a/src/devices/tech/security/se-linux.jd b/src/devices/tech/security/se-linux.jd
index d23be8c..acf9291 100644
--- a/src/devices/tech/security/se-linux.jd
+++ b/src/devices/tech/security/se-linux.jd
@@ -1,4 +1,4 @@
-page.title=Security-Enhanced Linux
+page.title=Validating Security-Enhanced Linux in Android
@jd:body
<!--
@@ -16,70 +16,121 @@
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>In Android 4.3,
-Android begins supporting Security-Enhanced Linux (SELinux), a tool for applying
-access control policies. SELinux enhances Android security, and contributions to
-it have been made by a number of companies and organizations; all Android code
-and contributors are publicly available for review on this same site <a
-href="http://source.android.com/">source.android.com</a>. With SELinux, Android
-can better control access to application data and system logs, reduce the
-effects of malicious software, and protect users from potential flaws in mobile
-code. </p>
+<h2 id="introduction">Introduction</h2>
+<p>
+As part of the Android <a href="{@docRoot}devices/tech/security/index.html">security
+model</a>, Android uses Security-Enhanced Linux (SELinux) to apply access
+control policies. SELinux enhances Android security, and contributions to it
+have been made by a number of companies and organizations; all Android code and
+contributors are publicly available for review on
+<a href="https://android.googlesource.com/">android.googlesource.com</a>. With SELinux,
+Android can
+better control access to application data and system logs, reduce the effects of
+malicious software, and protect users from potential flaws in code on mobile
+devices.
+</p>
+<p>
+Android includes SELinux in enforcing mode and a corresponding security policy
+that works by default across the <a
+href="https://android.googlesource.com/">Android Open Source
+Project</a>. In enforcing mode, illegitimate
+actions are prevented and all potential violations are logged by the kernel to
+<code>dmesg</code>. Android device manufacturers should gather information about errors so
+they may refine their software and SELinux policies before enforcing them.
+</p>
-<p>In this release, Android includes SELinux in permissive mode and a
-corresponding security policy that works by default across the <a
-href="https://android.googlesource.com/">Android Open Source Project</a>. In
-permissive mode, no actions are prevented. Instead, all potential violations are
-logged by the kernel to <code>dmesg</code>. This allows Android and Android device
-manufacturers to gather information about errors so they may refine their
-software and SELinux policies before enforcing them.</p>
+<h2 id="background">Background</h2>
+<p>
+Please note, Android upgraded its SELinux policy version to allow the SELinux
+mode to be set on a per-domain basis. For example, if you run all of your
+applications on a single domain, you could set that domain to be permissive and
+then have all other functions and their domains set to enforcement. Domains are
+associated with applications by the key used to sign each application. This
+setting is made at the top of each SELinux policy source (*.te) file.
+</p>
+<p>
+Android follows this model of isolating applications to a single domain. With
+this, only the root domain and root-level processes (such as <code>initd</code>,
+<code>installd</code> and
+<code>vold</code>) are now set to enforcing mode. <em>The application domain remains in
+permissive mode to allow further evaluation and prevent failures. Still, an
+errant application could trigger an action in the root domain that is not
+allowed, thereby causing the application to crash.</em>
+</p>
+<p>
+For this reason, device manufacturers should retain the default settings
+provided by Android and limit enforcing mode to the root domain only until
+they've resolved issues reported in dmesg. That said, device manufacturers may
+need to augment their SELinux implementation to account for their additions and
+other changes to the operating system. See the <em>Customization</em> section for
+instructions.
+</p>
-<h2 id="background">Background</h2> <p>Used properly, SELinux greatly limits the
-potential damage of compromised machines and accounts. When you adopt SELinux,
-you instill a structure by which software runs at only the minimum privilege
-level. This mitigates the effects of attacks and reduces the likelihood of
-errant processes overwriting or even transmitting data.</p>
-
-<p>SELinux provides a mandatory access control (MAC) umbrella over traditional
+<h2 id="mac">Mandatory access control</h2>
+<p>
+In conjunction with other Android security measures, Android's access control
+policy greatly limits the potential damage of compromised
+machines and accounts. Using tools like Android's discretionary and mandatory
+access controls gives you a structure to ensure your software runs
+only at the minimum privilege level. This mitigates the effects of
+attacks and reduces the likelihood of errant processes overwriting or even
+transmitting data.
+</p>
+<p>
+Starting in Android 4.3, SELinux provides a mandatory access control (MAC) umbrella over traditional
discretionary access control (DAC) environments. For instance, software must
typically run as the root user account to write to raw block devices. In a
traditional DAC-based Linux environment, if the root user becomes compromised
that user can write to every raw block device. However, SELinux can be used to
label these devices so the user role assigned the root privilege can write to
only those specified in the associated policy. In this way, root cannot
-overwrite data and system settings outside of the specific raw block device.</p>
+overwrite data and system settings outside of the specific raw block
+device.
+</p>
+<p>
+See the <em>Use Cases</em> section for more examples of threats and ways to address
+them with SELinux.
+</p>
-<p>See the <em>Use Cases</em> section for more examples of threats and ways to
-address them with SELinux.</p>
-
-<h2 id="implementation">Implementation</h2> <p>Android’s initial SELinux
-implementation is launching in permissive mode - rather than the non-functional
-disabled mode or the most stringent enforcing mode - to act as a reference and
-facilitate testing and development.</p>
-
-<p>SELinux is launching in permissive mode on Android to enable the first phase
-of policy development, and it is accompanied by everything you need to enable
-SELinux now.</p>
-
-<p>You merely need to integrate the <a
-href="https://android.googlesource.com/kernel/common/">latest Android kernel</a>
-and then incorporate the files found in the ~<a
+<h2 id="implementation">Implementation</h2>
+<p>
+Android's SELinux implementation is in enforcing mode - rather than the
+non-functional disabled mode or the notification-only permissive mode - to act
+as a reference and facilitate testing and development. Although enforcing mode
+is set globally, please remember this can be overridden on a per-domain basis
+as is in the case of the application domain.
+</p>
+<p>
+SELinux for Android is accompanied by everything you need to enable SELinux
+now. You merely need to integrate the <a
+href="https://android.googlesource.com/kernel/common/">latest Android
+kernel</a> and then incorporate the files found in the
+~<a
href="https://android.googlesource.com/platform/external/sepolicy/">platform/external/sepolicy</a>
-directory:<br>
+directory (where examples can also be found):<br/>
<a
href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/</a>
-<br>
+<br/>
<a
-href="https://android.googlesource.com/platform/external/sepolicy/">https://android.googlesource.com/platform/external/sepolicy/</a></p>
+href="https://android.googlesource.com/platform/external/sepolicy/">https://android.googlesource.com/platform/external/sepolicy/</a>
+</p>
-<p>Those files when compiled comprise the SELinux kernel security policy and
-cover the upstream Android operating system. Place those files within the
-<root>/device/manufacturer/device-name/sepolicy directory.</p>
-
-<p>Then just update your <code>BoardConfig.mk</code> makefile - located in the
-<device-name> directory containing the sepolicy subdirectory - to
-reference the sepolicy subdirectory once created, like so:</p>
+</p>
+ Those files when compiled comprise the SELinux kernel security policy and cover
+the upstream Android operating system. Place those files within the
+<root>/device/manufacturer/device-name/sepolicy directory.<br/>
+Then just update your <code>BoardConfig.mk</code> makefile - located in the <device-name>
+directory containing the sepolicy subdirectory - to reference the sepolicy
+subdirectory once created, like so:
+</p>
<pre>
BOARD_SEPOLICY_DIRS := \
@@ -91,88 +142,100 @@
sepolicy.te
</pre>
-<p>After rebuilding your device, it is enabled with SELinux. You can now either
+<p>
+After rebuilding your device, it is enabled with SELinux. You can now either
customize your SELinux policies to accommodate your own additions to the Android
operating system as described in the <em>Customization</em> section or verify
-your existing setup as covered in the <em>Validation</em> section.</p>
+your
+existing setup as covered in the <em>Validation</em> section.
+</p>
-<h2 id="customization">Customization</h2> <p>Once you’ve integrated this
-base level of functionality and thoroughly analyzed the results, you may add
-your own policy settings to cover your customizations to the Android operating
-system. Of course, these policies must still meet the <a
-href="{@docRoot}compatibility/index.html">Android Compatibility
-program</a> requirements and not remove the default SELinux settings.</p>
-
-<p>Manufacturers should not remove existing security settings. Otherwise, they
-risk breaking the Android SELinux implementation and the applications it
-governs. This includes third-party applications that will likely need to be
-improved to be compliant and operational. Applications must require no
-modification to continue functioning on SELinux-enabled devices.</p>
-
-<p>See section 9.7 of the Android 4.3 Compatibility Definition document for
-specific requirements:<br><a
-href="{@docRoot}compatibility/android-4.3-cdd.pdf">http://source.android.com/compatibility/android-4.3-cdd.pdf</a></p>
-
-<p>SELinux uses a whitelist approach, meaning it grants special privileges based
-upon role. Because the default policy provided by Android is so permissive, OEMs
-have great leeway in strengthening it. Here is how we recommend proceeding:</p>
+<h2 id="customization">Customization</h2>
+<p>
+Once you've integrated this base level of functionality and thoroughly analyzed
+the results, you may add your own policy settings to cover your customizations
+to the Android operating system. Of course, these policies must still meet the
+<a href="http://source.android.com/compatibility/index.html">Android
+Compatibility
+program</a> requirements and
+not remove the default SELinux settings.
+</p>
+<p>
+Manufacturers should not remove existing security settings. Otherwise, they risk
+breaking the Android SELinux implementation and the applications it governs.
+This includes third-party applications that will likely need to be improved to
+be compliant and operational. Applications must require no modification to
+continue functioning on SELinux-enabled devices.
+</p>
+<p>
+See the <em>Kernel Security Features</em> section of the Android Compatibility
+Definition document for specific requirements:<br/>
+<a
+href="http://source.android.com/compatibility/index.html">http://source.android.com/compatibility/index.html</a>
+</p>
+<p>
+SELinux uses a whitelist approach, meaning it grants special privileges based
+upon role. Since Android's default SELinux policy already supports the Android
+Open Source Project, OEMs are not required to modify SELinux settings in any
+way. If they do customize SELinux settings, they should take great care not to
+break existing applications. Here is how we recommend proceeding:
+</p>
<ol>
-<li>
-<p>Use the <a
-href="https://android.googlesource.com/kernel/common/">latest Android
-kernel</a>.</p> </li>
-<li>
-<p>Adopt the <a
+<li>Use the <a href="https://android.googlesource.com/kernel/common/">latest
+Android
+kernel</a>.</li>
+<li>Adopt the <a
href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of
-least privilege</a>.</p></li>
-<li>
-<p>Address only your own additions to
-Android. The default policy works with the <a
-href="https://android.googlesource.com/">Android Open Source Project</a>
-codebase automatically.</p></li>
-<li>
-<p>Compartmentalize software components
-into modules that conduct singular tasks.</p></li>
-<li>
-<p>Create SELinux
-policies that isolate those tasks from unrelated functions.</p></li>
-<li>
-<p>Put those policies in *.te files (the extension for SELinux policy source
-files) within the <root>/device/manufacturer/device-name/sepolicy
-directory.</p></li>
-<li>
-<p>Release your SELinux implementation in permissive
-mode first.</p></li>
-<li><p>Analyze results and refine policy settings.</p>
-</li>
+least
+privilege</a>.</li>
+<li>Address only your own additions to Android. The default policy works with
+the
+<a href="https://android.googlesource.com/">Android Open Source Project</a>
+codebase
+automatically.</li>
+<li>Compartmentalize software components into modules that conduct singular
+tasks.</li>
+<li>Create SELinux policies that isolate those tasks from unrelated
+functions.</li>
+<li>Put those policies in *.te files (the extension for SELinux policy source
+files) within the <root>/device/manufacturer/device-name/sepolicy
+directory.</li>
+<li>Release your SELinux implementation in permissive mode first.</li>
+<li>Analyze results and refine policy settings.</li>
</ol>
-<p>Once integrated, OEM Android development should include a step to ensure
-SELinux compatibility going forward. In an ideal software development process,
-SELinux policy changes only when the software model changes and not the actual
-implementation.</p>
-
-<p>As device manufacturers begin to customize SELinux, they should first audit
-their additions to Android. If you’ve added a component that conducts a
-new function, the manufacturer will need to ensure the component meets the
-security policy applied by Android, as well as any associated policy crafted by
-the OEM, before turning on enforcement.</p>
-
-<p>To prevent unnecessary issues, it is better to be overbroad and
-over-compatible than too restrictive and incompatible, which results in broken
-device functions. Conversely, if a manufacturer’s changes will benefit
-others, it should supply the modifications to the default SELinux policy as a <a
-href="{@docRoot}source/submit-patches.html">patch</a>. If the
-patch is applied to the default security policy, the manufacturer will no longer
-need to make this change with each new Android release.</p>
+<p>
+Once integrated, OEM Android development should include a step to ensure
+SELinux
+compatibility going forward. In an ideal software development process, SELinux
+policy changes only when the software model changes and not the actual
+implementation.
+</p>
+<p>
+As device manufacturers begin to customize SELinux, they should first audit
+their additions to Android. If they've added a component that conducts a new
+function, the manufacturers will need to ensure the component meets the security
+policy applied by Android, as well as any associated policy crafted by the OEM,
+before turning on enforcement.
+</p>
+<p>
+To prevent unnecessary issues, it is better to be overbroad and over-compatible
+than too restrictive and incompatible, which results in broken device functions.
+Conversely, if a manufacturer's changes will benefit others, it should supply
+the modifications to the default SELinux policy as a
+<a href="http://source.android.com/source/submit-patches.html">patch</a>. If the
+patch is
+applied to the default security policy, the manufacturer will no longer need to
+make this change with each new Android release.
+</p>
<h2 id="use-cases">Use Cases</h2> <p>Here are specific examples of exploits to
consider when crafting your own software and associated SELinux policies:</p>
<p><strong>Symlinks</strong> - Because symlinks appear as files, they are often read
just as that. This can lead to exploits. For instance, some privileged components such
-as init change the permissions of certain files, sometimes to be excessively
+as <code>init</code> change the permissions of certain files, sometimes to be excessively
open.</p>
<p>Attackers might then replace those files with symlinks to code they control,
@@ -224,7 +287,11 @@
<root>/device/manufacturer/device-name/sepolicy directory These files
define domains and their labels. The new policy files get concatenated with the
existing policy files during compilation into a single SELinux kernel policy
-file.</p></li>
+file.</p>
+<p><strong>Important</strong>:Do not alter the app.te file provided by the
+Android Open Source Project. Doing so risks breaking all third-party applications.
+</p>
+</li>
<li>
<p><em>Updated <code>BoardConfig.mk</code> makefile</em> - Located in the
<device-name> directory containing the sepolicy subdirectory. It must be
@@ -268,20 +335,19 @@
<h2 id="validation">Validation</h2> <p>Android strongly encourages OEMs to test
their SELinux implementations thoroughly. As manufacturers implement SELinux,
they should initially release their own policies in permissive mode. If
-possible, apply the new policy to devices of employees first as a test.</p>
+possible, apply the new policy to a test pool of devices first.</p>
<p>Once applied, make sure SELinux is running in the correct mode on the device
by issuing the command: <code>getenforce</code></p>
-<p>This will print the SELinux mode: either Disabled, Enforcing, or Permissive.
-If permissive, you are compliant. Enforcing is explicitly not compliant in
-Android 4.3. (Because of its risk, enforcing mode comes with a much heavier
-testing burden.)</p>
+<p>This will print the global SELinux mode: either Disabled, Enforcing, or Permissive.
+Please note, this command shows only the global SELinux mode. To determine the
+SELinux mode for each domain, you must examine the corresponding files.</p>
<p>Then check for errors. Errors are routed as event logs to <code>dmesg</code>
and viewable locally on the device. Manufacturers should examine the SELinux output
to <code>dmesg</code> on these devices and refine settings prior to public release in
-permissive mode.</p>
+permissive mode and eventual switch to enforcing mode.</p>
<p>With this output, manufacturers can readily identify when system users or
components are in violation of SELinux policy. Manufacturers can then repair
@@ -289,7 +355,29 @@
both.</p>
<p>Specifically, these log messages indicate what roles and processes would fail
-under policy enforcement and why. Android is taking this information, analyzing
+under policy enforcement and why. Here is an example:</p>
+
+<pre>
+denied { connectto } for pid=2671 comm="ping" path="/dev/socket/dnsproxyd"
+scontext=u:r:shell:s0 tcontext=u:r:netd:s0 tclass=unix_stream_socket
+</pre>
+
+<p>Interpret this output like so:</p>
+<ul>
+<li>The { connectto } above represents the action being taken. Together with the
+tclass at the end (unix_stream_socket) it tells you roughly what was being done
+to what. In this case, something was trying to connect to a unix stream
+socket.</li>
+<li>The scontext (u:r:shell:s0) tells you what context initiated the action. In
+this case this is something running as the shell.</li>
+<li>The tcontext (u:r:netd:s0) tells you the context of the action’s target. In
+this case, that’s a unix_stream_socket owned by netd.</li>
+<li>The comm="ping" at the top gives you an additional hint about what was being
+run at the time the denial was generated. In this case, it’s a pretty good
+hint.</li>
+</ul>
+
+<p>Android is taking this information, analyzing
it and refining its default security policy so that it works on a wide range of
Android devices with little customization. With this policy, OEMs must only
accommodate their own changes to the Android operating system.</p>
@@ -298,11 +386,7 @@
href="{@docRoot}compatibility/cts-intro.html">Android
Compatibility Test Suite</a> (CTS).</p> <p>As said, any new policies must still
meet the <a href="{@docRoot}compatibility/index.html">Android
-Compatibility program</a> requirements:<br><a
-href="{@docRoot}compatibility/android-4.3-cdd.pdf">http://source.android.com/compatibility/android-4.3-cdd.pdf</a></p>
-
-<p>If you run the devices through the CTS and find no errors in
-<code>dmesg</code>, you can consider your SELinux implementation compatible.</p>
+Compatibility program</a> requirements.</p>
<p>Finally, if possible, turn on enforcement internally (on devices of
employees) to raise the visibility of failures. Identify any user issues and
diff --git a/src/index.jd b/src/index.jd
index 08c2bef..5f2639a 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -43,7 +43,7 @@
<div class="col-8">
<h3>Updates</h3>
<a href="{@docRoot}source/index.html">
- <h4>Source Code Available for Android 4.4</h4>
+ <h4>Source Code Available for Android</h4>
<p>Android is an open-source software stack for a wide array of mobile devices with different form factors.
<img border="0" src="images/Android_Robot_100.png" alt="Android Partner icon" style="display:inline;float:right;margin:5px 10px">
We created Android in response to our own experiences launching mobile apps. We wanted to make sure there was
@@ -51,7 +51,7 @@
why we created Android and made its source code open.</p>
</a>
<a href="{@docRoot}compatibility/index.html">
- <h4>Compatibility Definition for Android 4.4</h4>
+ <h4>Compatibility Definition for Android</h4>
<p>Android's purpose is to establish an open platform for developers to build innovative apps. The Android
Compatibility program defines the technical details of the Android platform and provides tools for device manufacturers to
ensure developers' apps run on a variety of devices.</p>
