Docs: Add Security to top tab, create its nav file
Bug: 24908502
Change-Id: I70037156111410d7b54be11995c4e3fa50ea4acc
diff --git a/src/security/authentication/fingerprint-hal.jd b/src/security/authentication/fingerprint-hal.jd
new file mode 100644
index 0000000..f2bbed7
--- /dev/null
+++ b/src/security/authentication/fingerprint-hal.jd
@@ -0,0 +1,174 @@
+page.title=Fingerprint HAL
+@jd:body
+
+<!--
+ Copyright 2015 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=overview>Overview</h2>
+
+<p>If a device has a fingerprint sensor, a user can enroll one or more
+fingerprints and then use their fingerprints to unlock the device and perform
+other tasks.</p>
+
+<p>Android uses the Fingerprint Hardware Abstraction Layer (HAL) to connect to a
+vendor-specific library and fingerprint hardware, e.g. a fingerprint sensor.</p>
+
+<p>To implement the Fingerprint HAL, you must implement
+<a href="#major_functions_in_the_fingerprint_hal">functions</a>
+in <code>fingerprint.h</code> (<code>/hardware/libhardware/include/hardware/fingerprint.h</code>)
+in a vendor-specific library; please see the comments in
+the <a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/fingerprint.h"><code>fingerprint.h</code></a> file.</p>
+
+<h3 id=fingerprint_matching_flow>Fingerprint matching flow</h3>
+
+<p>The following is a high-level flow for fingerprint matching. This flow assumes
+that a fingerprint already has been enrolled on the device, i.e. the
+vendor-specific library already has enrolled a template for the fingerprint.
+Also see <a href="index.html">Authentication</a>.</p>
+
+<p>The fingerprint sensor of a device generally is idle. But in response to a call
+to the <code>authenticate</code> or <code>enroll</code> function, the fingerprint
+sensor listens for a touch (and perhaps the screen
+wakes up when a user touches the fingerprint sensor).</p>
+
+<ol>
+ <li>The user places a finger on the fingerprint sensor, and the vendor-specific
+library determines if there is a match based on the current set of enrolled
+templates.
+ <li>The result of step 1 is passed to the Fingerprint HAL, which notifies
+<code>fingerprintd</code> (the Fingerprint daemon) of a fingerprint authentication.
+</ol>
+
+<p>Note that as more templates are stored on a single device, the time needed for
+matching is increased.</p>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>The <strong>Fingerprint HAL</strong> interacts with the following components:</p>
+
+<ul>
+ <li><strong>FingerprintManager API</strong>. Interacts directly with an app in an app process.
+ <ul>
+ <li>Each app has an instance of FingerprintManager.
+ <li>FingerprintManager is a wrapper that communicates with FingerprintService.
+ </ul>
+ <li><strong>FingerprintService</strong>. A singleton service that operates in the system
+ process, which handles
+communication with <code>fingerprintd</code>.
+ <li><strong>fingerprintd (Fingerprint daemon)</strong>. A C/C++ implementation of the
+ binder interface from FingerprintService. The
+<code>fingerprintd</code> daemon operates in its own process and wraps the Fingerprint HAL
+vendor-specific library.
+ <li><strong>Fingerprint HAL vendor-specific library</strong>. A hardware vendor's
+ implementation of the Fingerprint HAL. The
+vendor-specific library communicates with the device-specific hardware.
+ <li><strong>Keystore API and Keymaster</strong>. These components provide hardware-backed cryptography
+ for secure key storage
+ in a Trusted Execution Environment (TEE).
+</ul>
+
+<p>As shown in the following diagram, a vendor-specific HAL implementation needs
+to use the communication protocol required by a TEE.</p>
+
+<img src="../images/fingerprint-data-flow.png" alt="Data flow for fingerprint authentication" id="figure1" />
+
+<p class="img-caption"><strong>Figure 1.</strong> High-level data flow for fingerprint authentication</p>
+
+<p>Thus, raw images and processed fingerprint features must not be passed in
+untrusted memory. All such biometric data needs to be secured within sensor
+hardware or trusted memory. (Memory inside the TEE is considered as trusted
+memory; memory outside the TEE is considered untrusted.)</p>
+
+<p>Rooting must not compromise biometric data.</p>
+
+<p>As shown in the following diagram, <code>fingerprintd</code> makes calls through the
+Fingerprint HAL to the vendor-specific library to enroll fingerprints and
+perform other operations.</p>
+
+<img src="../images/fingerprint-daemon.png" alt="Interaction with fingerprintd" id="figure2" />
+<p class="img-caption"><strong>Figure 2.</strong> Interaction of the
+fingerprint daemon (<code>fingerprintd</code>) with the fingerprint vendor-specific library</p>
+
+<h2 id=fingerprint_implementation_guidelines>Fingerprint implementation guidelines</h2>
+
+<p>The guidelines in this section are intended to ensure the following:</p>
+
+<ul>
+ <li>Fingerprint data is not leaked
+ <li>Fingerprint data is removed when a user is removed from a device
+</ul>
+
+<p>Here are the guidelines:</p>
+
+<ol>
+ <li>Raw fingerprint data or derivatives (e.g. templates) must never be accessible
+from outside the sensor driver or Trusted Execution Environment (TEE). Hardware
+access must be limited to the TEE, if the hardware supports it, and must be protected by
+an SELinux policy. That is, the Serial Peripheral Interface (SPI) channel must
+be accessible only to the TEE, and there must be an explicit SELinux policy on
+all device files.
+ <li>Fingerprint acquisition, enrollment and recognition must occur inside the TEE.
+ <li>Only the encrypted form of the fingerprint data can be stored on the file
+system, even if the file system itself is encrypted.
+ <li>Fingerprint templates must be signed with a private, device-specific key, for
+example with AES, with at least the absolute file-system path, group and finger
+ID such that template files are inoperable on another device or for anyone
+other than the user that enrolled them on the same device. For example, copying
+the fingerprint data from a different user on the same device, or from another
+device, must not work.
+ <li>Implementations must either use the file system path provided by the
+ <code>set_active_group()</code> function or provide a way to erase all user template data when the user
+is removed. It is strongly recommended that fingerprint template files
+be stored as encrypted in the path provided. If this is infeasible due to TEE
+storage requirements, then the implementer must add hooks to ensure removal of
+the data when the user is removed.
+</ol>
+
+<h2 id=major_functions_in_the_fingerprint_hal>Major functions in the Fingerprint HAL</h2>
+
+<p>Below are the major functions in the <code>/hardware/libhardware/include/hardware/fingerprint.h</code> file; see the detailed descriptions in that
+file.</p>
+
+<ul>
+ <li><strong>enroll.</strong> Switches the HAL state machine to start the collection and storage of a
+fingerprint template. As soon as enrollment is complete, or after a timeout,
+the HAL state machine is returned to the idle state.
+ <li><strong>pre_enroll.</strong> Generates a unique token to indicate the start of a fingerprint enrollment.
+Provides a token to the <code>enroll</code> function to ensure there was prior authentication, e.g. using a password. The
+token is wrapped and, for example, HMAC'd, once the device credential is
+confirmed, to prevent tampering. The token must be checked during enrollment to
+verify that the token is still valid.
+ <li><strong>get_authenticator_id.</strong> Returns a token associated with the current fingerprint set.
+ <li><strong>cancel.</strong> Cancels any pending enroll or authenticate operations. The HAL state machine
+is returned to the idle state.
+ <li><strong>enumerate.</strong> Synchronous call for enumerating all known fingerprint templates.
+ <li><strong>remove.</strong> Deletes a fingerprint template.
+ <li><strong>set_active_group.</strong> Restricts a HAL operation to a set of fingerprints that belong to a specified
+group (identified by a group identifier, or GID).
+ <li><strong>authenticate.</strong> Authenticates a fingerprint-related operation (identified by an operation ID).
+ <li><strong>set_notify.</strong> Registers a user function that will get notifications from the HAL. If the HAL
+state machine is in a busy state, the function is blocked until the HAL leaves
+the busy state.
+</ul>
+
diff --git a/src/security/authentication/gatekeeper.jd b/src/security/authentication/gatekeeper.jd
new file mode 100644
index 0000000..9d760bc
--- /dev/null
+++ b/src/security/authentication/gatekeeper.jd
@@ -0,0 +1,192 @@
+page.title=Gatekeeper
+@jd:body
+
+<!--
+ Copyright 2015 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=overview>Overview</h2>
+
+<p>The Gatekeeper subsystem performs device pattern/password authentication in a
+Trusted Execution Environment (TEE). Gatekeeper enrolls and verifies passwords
+via an HMAC with a hardware-backed secret key. Additionally, Gatekeeper
+throttles consecutive failed verification attempts and must refuse to service
+requests based on a given timeout and a given number of consecutive failed
+attempts.</p>
+
+<p>When users verify their passwords, Gatekeeper uses the TEE-derived shared
+secret to sign an authentication attestation to
+send to <a href="keymaster.html">Keymaster</a>. That is, a
+Gatekeeper attestation notifies Keymaster that authentication-bound keys (for
+example, keys that apps have created) can be released for use by apps.</p>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>Gatekeeper involves three main components:</p>
+
+<ul>
+ <li><strong>gatekeeperd (Gatekeeper daemon)</strong>.
+ A C++ binder service containing platform-independent logic and corresponding
+to the <code>GateKeeperService</code> Java interface.
+ <li><strong>Gatekeeper Hardware Abstraction Layer (HAL)</strong>.
+ The HAL interface in <code>hardware/libhardware/include/hardware/gatekeeper.h</code>,
+ and the implementing module.
+ <li><strong>Gatekeeper (TEE)</strong>.
+ The TEE counterpart of <code>gatekeeperd</code>. A TEE-based implementation of Gatekeeper.
+</ul>
+
+<p>To implement Gatekeeper:</p>
+
+<ul>
+ <li>Implement the Gatekeeper HAL, specifically the functions in <code>gatekeeper.h</code>
+ (<code>hardware/libhardware/include/hardware/gatekeeper.h</code>). See <a href="#hal_implementation">HAL Implementation</a>.
+ <li>Implement the TEE-specific Gatekeeper component, in part based on the following
+header file: <code>system/gatekeeper/include/gatekeeper/gatekeeper.h</code>. This
+header file includes pure virtual functions for creating and accessing
+keys, as well as for computing signatures.
+See <a href="#trusty_and_other_implementations">Trusty and other implementations</a>.
+</ul>
+
+<p>As shown in the following diagram, the <code>LockSettingsService</code> makes a request (via
+Binder) that reaches the <code>gatekeeperd</code> daemon in the Android OS. The <code>gatekeeperd</code>
+daemon makes a request that reaches its counterpart (Gatekeeper) in the TEE.</p>
+
+<img src="../images/gatekeeper-flow.png" alt="Gatekeeper flow" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> High-level data flow for authentication by GateKeeper</p>
+
+<p>The <code>gatekeeperd</code> daemon gives the Android framework APIs access to the HAL, and
+participates in reporting device <a href="index.html">authentications</a> to Keymaster.
+The <code>gatekeeperd</code> daemon runs in its own process, separate from the system
+server.</p>
+
+<h2 id=hal_implementation>HAL Implementation</h2>
+
+<p>The <code>gatekeeperd</code> daemon uses the HAL to interact
+with the <code>gatekeeperd</code> daemon's TEE
+counterpart for password authentication. The HAL implementation must be able to
+sign (enroll) and verify blobs. All implementations are expected to adhere to
+the standard format for the authentication token (AuthToken) generated on each
+successful password verification. The contents and semantics of the AuthToken
+are described in <a href="index.html">Authentication</a>.</p>
+
+<p>Specifically, an implementation of the <code>gatekeeper.h</code> header file (in the
+<code>hardware/libhardware/include/hardware</code> folder) needs to implement the
+<code>enroll</code> and <code>verify</code> functions.</p>
+
+<p>The <code>enroll</code> function takes a password blob, signs it, and returns the signature
+as a handle. The returned blob (from a call to <code>enroll</code>) must have the structure
+shown in <code>system/gatekeeper/include/gatekeeper/password_handle.h</code>.</p>
+
+<p>The <code>verify</code> function needs to compare the signature produced by the provided password and
+ensure that it matches the enrolled password handle.</p>
+
+<p>The key used to enroll and verify must never change, and should be re-derivable
+at every device boot.</p>
+
+<h2 id=trusty_and_other_implementations>Trusty and other implementations</h2>
+
+<p>The Trusty operating system is Google's open source trusted OS for TEE
+environments. It contains an approved implementation of GateKeeper. However,
+<strong>any TEE OS</strong> can be used for the implementation of Gatekeeper.
+The TEE <strong>must</strong> have access to a hardware-backed key as well as a secure,
+monotonic clock <strong>that ticks in suspend</strong>.</p>
+
+<p>Trusty uses an internal IPC system to communicate a shared secret directly
+between Keymaster and the Trusty implementation of Gatekeeper ("Trusty
+Gatekeeper"). This shared secret is used for signing AuthTokens that will be
+sent to Keymaster, providing attestations of password verification. Trusty
+Gatekeeper requests the key from Keymaster for each use and does not persist
+or cache the value. Implementations are free to share this secret in any way
+that does not compromise security.</p>
+
+<p>The HMAC key, used to enroll and verify passwords, is derived and kept solely
+in GateKeeper.</p>
+
+<p>The Android tree provides a generic C++ implementation of GateKeeper, requiring
+only the addition of device-specific routines to be complete. To implement a
+TEE Gatekeeper with device-specific code for your TEE, please refer to the
+functions and comments in the following file:</p>
+<pre>
+system/gatekeeper/include/gatekeeper/gatekeeper.h
+</pre>
+
+<p>For the TEE GateKeeper, the primary responsibilities of a compliant
+implementation are:</p>
+
+<ul>
+ <li>Adherence to the Gatekeeper HAL
+ <li>Returned AuthTokens must be formatted according to the AuthToken specification
+(described in <a href="index.html">Authentication</a>)
+ <li>The TEE Gatekeeper must be able to share an HMAC key with Keymaster, either by
+requesting the key through a TEE IPC on demand or maintaining a valid cache of
+the value at all times
+</ul>
+
+<h2 id=user_sids>User SIDs</h2>
+
+<p>A User Secure ID (User SID) is the TEE representation of a user.
+The User SID has no strong connection to an Android user ID.</p>
+
+<p>A User SID is generated with a cryptographic
+PRNG whenever a user enrolls a new password without providing a previous one.
+This is known as an "untrusted" re-enroll.
+A "trusted" re-enroll occurs when a user provides a valid, previous password.
+In this case, the User SID is migrated to the new password handle,
+conserving the keys that were bound to it.
+The Android framework does not allow for an "untrusted" re-enroll under regular circumstances.</p>
+
+<p>The User SID is HMAC'ed along with the password in the password handle when the
+password is enrolled.</p>
+
+<p>User SIDs are written into the AuthToken returned by the <code>verify</code>
+function and associated to all authentication-bound Keymaster keys. For
+information about the AuthToken format and Keymaster, see
+<a href="index.html">Authentication</a>.
+Since an untrusted call to the <code>enroll</code> function
+will change the User SID, the call will render the keys bound to that password useless.</p>
+
+<p>Attackers can change the password for the device if they control the Android
+OS, but they will destroy root-protected, sensitive keys in the process.</p>
+
+<h2 id=request_throttling>Request throttling</h2>
+
+<p>GateKeeper must be able to securely throttle brute-force attempts on a user
+credential. As shown in the <code>gatekeeper.h</code>
+file (in <code>hardware/libhardware/include/hardware</code>),
+the HAL provides for returning a timeout in milliseconds. The timeout
+informs the client not to call GateKeeper again until after the timeout has
+elapsed. GateKeeper should not service requests if there is a pending timeout.</p>
+
+<p>GateKeeper must write a failure counter before verifying a user password. If
+the password verification succeeds, the failure counter should be cleared. This
+prevents attacks that prevent throttling by disabling the embedded MMC (eMMC)
+after issuing a <code>verify</code> call. The <code>enroll</code> function also verifies
+the user password (if provided) and so must be throttled in the same way.</p>
+
+<p>If supported by the device, it is highly recommended that the failure counter
+be written to secure storage. If the device does not support
+file-based encryption, or if secure storage is too slow, implementations may
+use RPMB directly.</p>
+
+
+
+
diff --git a/src/security/authentication/index.jd b/src/security/authentication/index.jd
new file mode 100644
index 0000000..86564eb
--- /dev/null
+++ b/src/security/authentication/index.jd
@@ -0,0 +1,250 @@
+page.title=Authentication
+@jd:body
+
+<!--
+ Copyright 2015 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=overview>Overview</h2>
+
+<p>Android 6.0 introduces the concept of user-authentication-gated cryptographic
+keys. To achieve this, two key components need to work together.
+First is the cryptographic key storage and service provider, which stores
+cryptographic keys and provides standard crypto routines on top of them. Second
+is any number of user authenticators that may attest to the user's presence
+and/or successful authentication.</p>
+
+<p>The cryptographic key storage in Android is provided by the keystore service and Keymaster.
+(Also see information about
+the <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore system</a>,
+at the framework level, which is backed by the keystore service.) For Android 6.0,
+the two supported authentication components are Gatekeeper (for
+PIN/pattern/password authentication) and Fingerprint (for fingerprint
+authentication). These components communicate their authentication
+state with the keystore service via an authenticated channel.</p>
+
+<ul>
+ <li><strong>The keystore service and <a href="keymaster.html">Keymaster</a>.</strong> Cryptographic services,
+ including hardware-backed cryptography for key storage,
+ which might include a Trusted Execution Environment (TEE).</li>
+ <li><strong><a href="gatekeeper.html">Gatekeeper</a>.</strong> Components for PIN, pattern, and password authentication.</li>
+ <li><strong><a href="fingerprint-hal.html">Fingerprint</a>.</strong> Components for fingerprint authentication.</li>
+</ul>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>The Gatekeeper and Fingerprint components work with Keymaster and other
+components to support the use of hardware-backed <a href="#authentication_token_format">authentication tokens</a> (referred to below as "AuthTokens").</p>
+
+<h3 id=enrollment>Enrollment</h3>
+
+<p>Upon first boot of the device after a factory reset, all authenticators are prepared to receive
+credential enrollments from the user.</p>
+
+<p>The user must initially enroll a PIN/pattern/password with Gatekeeper. This
+initial enrollment creates a randomly generated, 64-bit User SID (user secure
+identifier, described further below) that serves as an identifier for the user
+and as a binding token for the user's cryptographic material.
+This User SID is cryptographically bound to the user's password.
+As detailed below, successful authentications to Gatekeeper result in AuthTokens that contain the User SID
+for that password.</p>
+
+<p>When a user wants to change their credential, they must present their existing
+credential. If the existing credential is verified successfully, the User SID
+associated with the existing credential is transferred to the new credential.
+This allows the user to keep accessing their keys after changing their
+credential. If a user does not present their existing credential, the new one
+is enrolled with a fully random User SID. The user can access the device but
+keys created under the old User SID are permanently lost. This is known as an
+"untrusted enroll."</p>
+
+<p>Note that an untrusted enroll will not be allowed under normal circumstances by
+the Android framework, so most users won't ever see this functionality.
+However, forcible password resets either by a device administrator or an
+attacker may cause this to occur.</p>
+
+<h3 id=authentication>Authentication</h3>
+
+<p>Now that the user has set up a credential and received a User SID, they may
+proceed to start authentication.</p>
+
+<p>In the diagram below, authentication starts when a user provides a PIN,
+pattern, password, or fingerprint. All TEE components share a secret key which
+they use to authenticate each other's messages.</p>
+
+<img src="../images/authentication-flow.png" alt="Authentication flow" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Authentication flow</p>
+
+<p>The numbers in the following steps correspond to the numbers in the diagram
+above, and include reference to both the Android OS and the TEE OS: </p>
+
+<ol>
+ <li>A user provides a PIN, pattern, password, or fingerprint. The
+<code>LockSettingsService</code> or <code>FingerprintService</code> make a request via Binder to the
+Gatekeeperd or fingerprintd daemon in the Android OS. Note that fingerprint
+authentication occurs asynchronously after the fingerprint request is sent.
+ <li>This step involves <strong>either</strong> Gatekeeperd (option 1 below)
+ <strong>or</strong> fingerprintd (option 2 below),
+ depending on whether a pin/pattern/password, or fingerprint, is provided.
+ <ul>
+ <li>The Gatekeeperd daemon sends a pin, pattern, or password hash (received in step
+1) to its counterpart (Gatekeeper) in the TEE. If authentication in the TEE is
+successful, Gatekeeper in the TEE sends an AuthToken containing the
+corresponding User SID, signed with the AuthToken HMAC key, to its
+counterpart in the Android OS.
+ <li>Alternatively, the fingerprintd daemon, which listens for fingerprint events,
+sends the data (received in step 1) to its counterpart (Fingerprint) in the
+TEE. If authentication in the TEE is successful, Fingerprint in the TEE sends
+an AuthToken, signed with the AuthToken HMAC key, to its counterpart in the Android OS.
+ </ul>
+ <li>The Gatekeeperd or fingerprintd daemon receives a signed AuthToken and passes
+the AuthToken to the keystore service via an extension to
+the keystore service's Binder interface. Additionally, Gatekeeperd notifies the keystore service when
+the device is re-locked and when the device password changes.
+ <li>The keystore service passes to Keymaster the AuthTokens received from Gatekeeperd and
+fingerprintd, verifying the AuthTokens with the key shared with the Gatekeeper
+and Fingerprint trustlets. Keymaster trusts the timestamp in the token as the
+last authentication time and bases a key release decision (to allow an app to
+use the key) on the timestamp.
+</ol>
+
+<p class="note"><strong>Note:</strong> AuthTokens are invalidated whenever a device reboots.</p>
+
+<h2 id=authentication_token_format>Authentication token format</h2>
+
+<p>The AuthToken format described in the
+<a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/hw_auth_token.h"><code>hw_auth_token.h</code></a> file is
+necessary for token sharing and compatibility across languages and
+components. See the following file:</p>
+<pre>
+hardware/libhardware/include/hardware/hw_auth_token.h
+</pre>
+
+<p>A simple serialization protocol with the required fields is defined in the
+table below. The fields are fixed size.</p>
+
+<p>Field descriptions are below the table.</p>
+<table>
+ <tr>
+ <th><strong>Field</strong></th>
+ <th><strong>Type</strong></th>
+ <th><strong>Required or Optional</strong></th>
+ </tr>
+ <tr>
+ <td>AuthToken Version</td>
+ <td>1 byte</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Challenge</td>
+ <td>64-bit unsigned integer</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>User SID</td>
+ <td>64-bit unsigned integer</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Authenticator ID</td>
+ <td>64-bit unsigned integer in network order</td>
+ <td>Optional</td>
+ </tr>
+ <tr>
+ <td>Authenticator type</td>
+ <td>32-bit unsigned integer in network order</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>Timestamp</td>
+ <td>64-bit unsigned integer in network order</td>
+ <td>Required</td>
+ </tr>
+ <tr>
+ <td>AuthToken HMAC key (SHA-256)</td>
+ <td>256-bit blob</td>
+ <td>Required</td>
+ </tr>
+</table>
+
+<h3 id=field_descriptions>Field descriptions </h3>
+
+<p>This section describes the fields of the AuthToken table above.</p>
+
+<p><strong>AuthToken Version:</strong> Group tag for all fields below.</p>
+
+<p><strong>Challenge:</strong> A random integer to prevent replay attacks. Usually the ID of a requested
+crypto operation. Currently used by transactional fingerprint authorizations.
+If present, the AuthToken is valid only for crypto operations containing the
+same challenge.</p>
+
+<p><strong>User SID</strong>: Non-repeating user identifier tied cryptographically to all keys associated
+with device authentication. For more information, see the Gatekeeper page.</p>
+
+<p><strong>Authenticator ID (ASID)</strong>: Identifier used to bind to a specific authenticator policy. All
+authenticators have their own value of ASID that they can change according to
+their own requirements.</p>
+
+<p><strong>Authenticator Type</strong>: Either Gatekeeper or Fingerprint, as follows:</p>
+<table>
+ <tr>
+ <th><strong>Authenticator Type</strong></th>
+ <th><strong>Authenticator Name</strong></th>
+ </tr>
+ <tr>
+ <td>0x00</td>
+ <td>Gatekeeper</td>
+ </tr>
+ <tr>
+ <td>0x01</td>
+ <td>Fingerprint</td>
+ </tr>
+</table>
+
+<p><strong>Timestamp</strong>: Time (in milliseconds) since the most recent system boot.</p>
+
+<p><strong>AuthToken HMAC key</strong>: Keyed SHA-256 MAC of all fields except the HMAC field.</p>
+
+<h2 id=device_boot_flow>Device boot flow</h2>
+
+<p>On every boot of a device, the AuthToken HMAC key must be generated and shared
+with all TEE components (Gatekeeper, Fingerprint, and Keymaster). Thus, the HMAC key
+must be randomly generated every time the device reboots, for added protection against replay attacks.</p>
+
+<p>The protocol for sharing this HMAC key with all components is a
+platform-dependent implementation feature. The key must <strong>never</strong>
+be made available outside the TEE. Thus, if a TEE OS lacks an
+internal inter-process communication (IPC) mechanism,
+and the TEE needs to transfer the data through the untrusted OS, the transfer
+must be done via a secure key exchange protocol.</p>
+
+<p>The Trusty operating system, which runs next to Android, is an example of a
+TEE, but other TEEs can be used instead. Trusty uses an internal IPC system to
+communicate directly between Keymaster and Fingerprint or Gatekeeper. The HMAC
+key is kept solely in Keymaster. Fingerprint and Gatekeeper request the key
+from Keymaster for each use, and do not persist or cache the value.</p>
+
+<p>Note that no communication happens between applets in the TEE because some TEEs
+are lacking in IPC infrastructure. This also
+permits the keystore service to quickly deny requests that are bound to fail as it has
+knowledge of the authentication table in the system, saving a potentially
+costly IPC into the TEE.</p>
diff --git a/src/security/authentication/keymaster.jd b/src/security/authentication/keymaster.jd
new file mode 100644
index 0000000..8febf76
--- /dev/null
+++ b/src/security/authentication/keymaster.jd
@@ -0,0 +1,100 @@
+page.title=Keymaster
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>The availability of a trusted execution environment in a system on a chip (SoC)
+offers an opportunity for Android devices to provide hardware-backed, strong
+security services to the Android OS, to platform services, and even to
+third-party apps.</p>
+
+<p>Keymaster has been <a href="km-features.html">significantly enhanced</a>
+in Android 6.0 with the addition of symmetric cryptographic primitives,
+AES and HMAC, and the addition of an access control
+system for hardware-backed keys. Access controls are specified during key
+generation and enforced for the lifetime of the key. Keys can be restricted to
+be usable only after the user has authenticated, only at a specific usage
+velocity, and only for specified purposes or with specified cryptographic
+parameters. For more information, please see
+the <a href="km-implementer-ref.html">Implementer's Reference</a>.</p>
+
+<p>Before Keymaster 1.0, Android already had a simple, hardware-backed crypto
+services API: Keymaster versions 0.2 and 0.3, which provided only digital
+signing and verification operations, plus generation of
+asymmetric signing key pairs. This is already
+implemented on many devices, but there are many security goals that cannot
+easily be achieved with only a signature API. The intent of Keymaster 1.0 is to
+extend the Keymaster API to provide a broader range of capabilities.</p>
+
+<h2 id=goals>Goals</h2>
+
+<p>The goal of the Keymaster API is to provide a basic but adequate set of
+cryptographic primitives to allow the implementation of protocols using
+access-controlled, hardware-backed keys.</p>
+
+<p>In addition to expanding the range of cryptographic primitives, Keymaster v1.0
+adds the following:</p>
+
+<ul>
+ <li>A usage control scheme to allow key usage to be limited, to mitigate the risk
+of security compromise due to misuse of keys
+ <li>An access control scheme to enable restriction of keys to specified users,
+clients, and a defined time range
+</ul>
+
+<h2 id=architecture>Architecture</h2>
+
+<p>The Keymaster API is a Hardware Abstraction Layer module, which is a
+dynamically-loaded library. Implementations must not
+perform any sensitive operations in user space, or even in kernel space.
+Sensitive operations are delegated to a secure processor reached through some
+kernel interface. The resulting architecture looks something like the
+following:</p>
+
+<img src="../images/access-to-keymaster.png" alt="Access to Keymaster" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Access to Keymaster</p>
+
+<p>Within an Android device, the "client" actually consists of multiple layers
+(e.g. app, framework, keystore daemon), but that can be ignored for the
+purposes of this document. This means that the described API is low-level, used
+by platform-internal components, and not exposed to app developers. The
+higher-level API, for API level 23, is described on
+the <a href="http://developer.android.com/reference/java/security/KeyStore.html">Android Developer site</a>.</p>
+
+<p>The purpose of the <code>libkeymaster</code> library is not to implement the
+security-sensitive algorithms but only to
+marshal and unmarshal requests to the secure world. The wire format is
+implementation-defined.</p>
+
+<h2 id=compatibility_with_previous_versions>Compatibility with previous versions</h2>
+
+<p>The Keymaster v1.0 API is completely incompatible with the previously-released
+APIs, e.g. Keymaster v0.2 and v0.3.
+To facilitate interoperability on pre-Marshmallow devices that launched
+with the older Keymaster APIs, Keystore provides an adapter that provides
+the 1.0 API implemented with calls to the existing hardware library. The result
+cannot provide the full range of functionality in the
+1.0 API. In particular, it will only support RSA and ECDSA algorithms, and all
+of the key authorization enforcement will be performed by the adapter, in the
+non-secure world.</p>
diff --git a/src/security/authentication/km-features.jd b/src/security/authentication/km-features.jd
new file mode 100644
index 0000000..2b469c9
--- /dev/null
+++ b/src/security/authentication/km-features.jd
@@ -0,0 +1,412 @@
+page.title=Features
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>This page contains information about the features of <a href="keymaster.html">Keymaster</a> 1.0.</p>
+
+<h2 id=cryptographic_primitives>Cryptographic primitives</h2>
+
+<p>The <code>libkeymaster</code> library and Keymaster provide the following categories of operations:</p>
+
+<ul>
+ <li>Key generation
+ <li>Import and export of asymmetric keys (no key wrapping)
+ <li>Import of raw symmetric keys (again, no wrapping)
+ <li>Asymmetric encryption and decryption with appropriate padding modes
+ <li>Asymmetric signing and verification with digesting and appropriate padding
+modes
+ <li>Symmetric encryption and decryption in appropriate modes, including an AEAD
+mode
+ <li>Generation and verification of symmetric message authentication codes
+</ul>
+
+<p>Within each category, <code>libkeymaster</code> provides a mechanism for
+discovering the available options (algorithms,
+modes, etc.). But we also specify at least one required option, to ensure that
+client software can depend on the presence of the required primitives.</p>
+
+<p>Protocol elements, such as purpose, mode and padding, as well
+as <a href="#key_access_control">access control constraints</a>,
+must be specified when keys are generated or imported and are permanently
+bound to the key, ensuring the key cannot be used in any other way.</p>
+
+<p>In addition to the list above, there is one more service that Keymaster
+implementations must provide but which is not exposed as an API: Random number
+generation. This is used internally for generation of keys, Initialization
+Vectors (IVs), random padding and other elements of secure protocols that
+require randomness.</p>
+
+<h2 id=required_primitives>Required primitives</h2>
+
+<p>All implementations must provide:</p>
+
+<ul>
+ <li><a href="http://en.wikipedia.org/wiki/RSA_(cryptosystem)">RSA</a>
+ <ul>
+ <li>2048, 3072 and 4096-bit key support are required
+ <li>Support for public exponent F4 (2^16+1)
+ <li>Required padding modes for RSA signing are:
+ <ul>
+ <li>No padding (deprecated, will be removed in the future)
+ <li>RSASSA-PSS (<code>KM_PAD_RSA_PSS</code>)
+ <li>RSASSA-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code>)
+ </ul>
+ <li>Required digest modes for RSA signing are:
+ <ul>
+ <li>No digest (deprecated, will be removed in the future)
+ <li>SHA-256
+ </ul>
+ <li>Required padding modes for RSA encryption/decryption are:
+ <ul>
+ <li>RSAES-OAEP (<code>KM_PAD_RSA_OAEP</code>)
+ <li>RSAES-PKCS1-v1_5 (<code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code>)
+ </ul>
+ <li>Unpadded RSA encryption must not be supported
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Elliptic_Curve_DSA">ECDSA</a>
+ <ul>
+ <li>224, 256, 384 and 521-bit key support are required, using the NIST P-224,
+P-256, P-384 and P-521 curves, respectively
+ <li>Required digest modes for ECDSA are:
+ <ul>
+ <li>No digest (deprecated, will be removed in the future)
+ <li>SHA-256
+ </ul>
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Advanced_Encryption_Standard">AES</a>
+ <ul>
+ <li>128 and 256-bit keys are required
+ <li><a href="http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Cipher-block_chaining_.28CBC.29">CBC</a>,
+ CTR, ECB and and GCM. The GCM implementation must not allow the use of tags
+smaller than 96 bits or nonce lengths other than 96 bits.
+ <li>Padding modes <code>KM_PAD_NONE</code> and <code>KM_PAD_PKCS7</code> must
+ be supported for CBC and ECB modes. With no padding, CBC or ECB mode
+encryption must fail if the input isn't a multiple of the block size.
+ </ul>
+ <li><a href="http://en.wikipedia.org/wiki/Hash-based_message_authentication_code">HMAC</a>
+ <a href="http://en.wikipedia.org/wiki/SHA-2">SHA-256</a>, with any key size up to at least 32 bytes.
+</ul>
+</ul>
+
+<p>SHA1 and the other members of the SHA2 family (SHA-224, SHA384 and SHA512) are
+strongly recommended, but not required. Keystore will provide them in software
+if the hardware Keymaster implementation doesn't provide them.</p>
+
+<p>Some primitives are also recommended for interoperability with other systems:</p>
+
+<ul>
+ <li>Smaller key sizes for RSA
+ <li>Arbitrary public exponents for RSA
+</ul>
+
+<h2 id=key_access_control>Key access control</h2>
+
+<p>Hardware-based keys that can never be extracted from the device don't provide
+much security if an attacker can use them at will (though they're more secure
+than keys which <em>can</em> be exfiltrated). Thus, it's crucial that Keymaster enforce access controls.</p>
+
+<p>Access controls are defined as an "authorization list" of tag/value pairs.
+Authorization tags are 32-bit integers and the values are a variety of types.
+Some tags may be repeated to specify multiple values. Whether a tag may be
+repeated is specified in the documentation for the tag. When a key is created,
+the caller specifies an authorization list. The Keymaster implementation will
+modify the list to specify some additional information, such as whether the key
+has rollback protection, and return a "final" authorization list, encoded into
+the returned key blob. Any attempt to use the key for any cryptographic
+operation must fail if the final authorization list is modified.</p>
+
+<p>The set of possible tags is defined in the enumeration <code>keymaster_authorization_tag_t</code> and
+the set must be permanently fixed (though it can be extended).
+Names are prefixed with <code>KM_TAG_</code>. The top
+four bits of tag IDs are used to indicate the type.</p>
+
+<p>Possible types include:</p>
+
+<p><strong><code>KM_ENUM</code>:</strong> Many tags' values are defined in enumerations. For example, the possible
+values of <code>KM_TAG_PURPOSE</code> are defined in enum <code>keymaster_purpose_t</code>.</p>
+
+<p><strong><code>KM_ENUM_REP</code></strong>: Same as <code>KM_ENUM</code>, except that the tag may
+be repeated in an authorization list. Repetition
+indicates multiple authorized values. For example, an encryption key will
+likely have <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_DECRYPT</code>.</p>
+
+<p><strong><code>KM_UINT</code>:</strong> 32-bit unsigned integers. Example: <code>KM_TAG_KEY_SIZE</code></p>
+
+<p><strong><code>KM_UINT_REP</code></strong>: Same as <code>KM_UINT</code>, except that the tag may be
+repeated in an authorization list. Repetition indicates multiple authorized values.</p>
+
+<p><strong><code>KM_ULONG</code></strong>: 64-bit unsigned integers. Example: <code>KM_TAG_RSA_PUBLIC_EXPONENT</code></p>
+
+<p><strong><code>KM_ULONG_REP</code></strong>: Same as <code>KM_ULONG</code>, except that the tag may be
+repeated in an authorization list. Repetition
+indicates multiple authorized values.</p>
+
+<p><strong><code>KM_DATE</code></strong>: Date/time values, expressed as milliseconds since January 1, 1970.
+Example: <code>KM_TAG_PRIVKEY_EXPIRE_DATETIME</code></p>
+
+<p><strong><code>KM_BOOL</code></strong>: True or false. A tag of type <code>KM_BOOL</code> is assumed
+to be "false" if the tag is not present and "true" if present. Example: <code>KM_TAG_ROLLBACK_RESISTANT</code></p>
+
+<p><strong><code>KM_BIGNUM</code></strong>: Arbitrary-length integers, expressed as a byte array
+in big-endian order. Example: <code>KM_TAG_RSA_PUBLIC_EXPONENT</code></p>
+
+<p><strong><code>KM_BYTES</code></strong>: A sequence of bytes. Example: <code>KM_TAG_ROOT_OF_TRUST</code></p>
+
+<h3 id=hardware_vs_software_enforcement>Hardware vs. software enforcement</h3>
+
+<p>Not all Keymaster implementations will implement the same features. To support
+a variety of approaches, Keymaster 1.0 distinguishes between secure and
+non-secure world access control enforcement, which we call hardware and
+software enforcement, respectively.</p>
+
+<p>Implementations are required to:</p>
+
+<ul>
+ <li>Enforce exact matching (not enforcement) of all authorizations. Authorization
+lists in key blobs must exactly match the authorizations returned during key
+generation, including ordering. Any mismatch must cause an error diagnostic.
+ <li>Declare the authorizations whose semantic values are enforced.
+</ul>
+
+<p>The API mechanism for declaring hardware-enforced authorizations is in
+the <code>keymaster_key_characteristics_t</code> structure. It divides the authorization
+list into two sub-lists, <code>hw_enforced</code> and <code>sw_enforced</code>. The
+Keymaster implementation is responsible for placing the appropriate
+values in each, based on what it can enforce.</p>
+
+<p>In addition, the keystore daemon will implement software-based enforcement of <em>all</em> authorizations,
+whether they're enforced in hardware or not.</p>
+
+<p>For example, consider a TrustZone-based implementation that does not support
+key expiration. A key with an expiration date may still be created. That key's
+authorization list will include the tag <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> with
+the expiration date. A request to Keymaster for the key characteristics
+will find this tag in the <code>sw_enforced</code> list and the Keymaster implementation will
+not enforce the expiration
+requirement. However, attempts to use the key after expiration will be rejected
+by the keystore daemon.</p>
+
+<p>If the device is then upgraded with a Keymaster implementation that does
+support expiration, then a request for key characteristics will
+find <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code> in
+the <code>hw_enforced</code> list, and attempts to use the key after expiration will fail even if the
+keystore is somehow subverted or bypassed.</p>
+
+<h3 id=cryptographic_message_construction_authorizations>Cryptographic message construction authorizations</h3>
+
+<p>The following tags are used to define the cryptographic characteristics of
+operations using the associated key: <code>KM_TAG_ALGORITHM</code>, <code>KM_TAG_KEY_SIZE</code>,
+<code>KM_TAG_BLOCK_MODE</code>, <code>KM_TAG_PADDING</code>, <code>KM_TAG_CALLER_NONCE</code>, and <code>KM_TAG_DIGEST</code></p>
+
+<p><code>KM_TAG_PADDING</code>, <code>KM_TAG_DIGEST</code>, and <code>KM_PAD_BLOCK_MODE</code>
+are repeatable, meaning that multiple values may be associated with a single
+key, and the value to be used will be specified at operation time.</p>
+
+<h3 id=purpose>Purpose</h3>
+
+<p>Keys have an associated set of purposes, expressed as one or more authorization
+entries with tag <code>KM_TAG_PURPOSE</code>, which defines how they can be used. The purposes are:</p>
+
+<ul>
+ <li><code>KM_PURPOSE_ENCRYPT</code>
+ <li><code>KM_PURPOSE_DECRYPT</code>
+ <li><code>KM_PURPOSE_SIGN</code>
+ <li><code>KM_PURPOSE_VERIFY</code>
+</ul>
+
+<p>Any key can have any subset of these purposes. Note that some combinations
+create security problems. For example, an RSA key that can be used to both
+encrypt and to sign allows an attacker who can convince the system to decrypt
+arbitrary data to generate signatures.</p>
+
+<p>Other purposes for keys that may be added in the future include:</p>
+
+<ul>
+ <li>"Derive Key" purpose, for key derivation keys
+ <li>"Attest" purpose, for keys that can generate attestations of the Keymaster
+implementation and/or its environment
+ <li>"Wrap Key" purpose, for keys used to wrap keys for secure import or export
+</ul>
+
+<h3 id=import_and_export>Import and export</h3>
+
+<p>Keymaster supports export of public keys only, in X.509 format, and import of:</p>
+
+<ul>
+ <li>Public and private key pairs in DER-encoded PKCS#8 format, without
+password-based encryption, and
+ <li>Symmetric keys as raw bytes
+</ul>
+
+<p>Future versions will likely expand the import/export options.</p>
+
+<p>To ensure that imported keys can be distinguished from securely-generated
+keys, <code>KM_TAG_ORIGIN</code> is included in the appropriate key
+authorization list. For example, if a key
+was generated in secure hardware, <code>KM_TAG_ORIGIN</code> with
+value <code>KM_ORIGIN_GENERATED</code> will be found in
+the <code>hw_enforced</code> list of the key characteristics, while a key
+that was imported into secure
+hardware will have the value <code>KM_ORIGIN_IMPORTED</code>.</p>
+
+<h3 id=user_authentication>User authentication</h3>
+
+<p>Keymaster does not implement user authentication, but depends on other trusted
+apps which do. For the interface that must be implemented by these apps, see
+the Gatekeeper page.</p>
+
+<p>User authentication requirements are specified via two sets of tags. The first
+set indicate which user can use the key:</p>
+
+<ul>
+ <li><code>KM_TAG_ALL_USERS</code> indicates the key is usable by all users. If
+ present, <code>KM_TAG_USER_ID</code> and <code>KM_TAG_SECURE_USER_ID</code> must not be present.
+ <li><code>KM_TAG_USER_ID</code> has a numeric value specifying the ID of the authorized user.
+ Note that this
+is the Android user ID (for multi-user), not the application UID, and it is
+enforced by non-secure software only. If present, <code>KM_TAG_ALL_USERS</code> must not be present.
+ <li><code>KM_TAG_SECURE_USER_ID</code> has a 64-bit numeric value specifying the secure user ID
+ that must be provided
+in a secure authentication token to unlock use of the key. If repeated, the key
+may be used if any of the values is provided in a secure authentication token.
+</ul>
+
+<p>The second set indicate whether and when the user must be authenticated. If
+neither of these tags is present, but <code>KM_TAG_SECURE_USER_ID</code> is, authentication is
+required for every use of the key.</p>
+
+<ul>
+ <li><code>KM_NO_AUTHENTICATION_REQUIRED</code> indicates no user authentication is required, though
+ the key still may only be
+used by apps running as the user(s) specified by <code>KM_TAG_USER_ID</code>.
+ <li><code>KM_TAG_AUTH_TIMEOUT</code> is a numeric value specifying, in seconds, how fresh the user
+ authentication
+must be to authorize key usage. This applies only to private/secret key
+operations. Public key operations don't require authentication. Timeouts do not
+cross reboots; after a reboot, all keys are "never authenticated." The timeout
+may be set to a large value to indicate that authentication is required once
+per boot (2^32 seconds is ~136 years; presumably Android devices are rebooted
+more often than that).
+</ul>
+
+<h3 id=client_binding>Client binding</h3>
+
+<p>Client binding, the association of a key with a particular client application,
+is done via an optional client ID and some optional client data (<code>KM_TAG_APPLICATION_ID</code>
+and <code>KM_TAG_APPLICATION_DATA</code>, respectively). Keymaster treats these values as opaque blobs,
+only ensuring
+that the same blobs presented during key generation/import are presented for
+every use and are byte-for-byte identical. The client binding data is not
+returned by Keymaster. The caller must know it in order to use the key.</p>
+
+<h3 id=expiration>Expiration</h3>
+
+<p>Keymaster supports restricting key usage by date. Key start of validity and key
+expirations can be associated with a key and Keymaster will refuse to perform
+key operations if the current date/time is outside of the valid range. The key
+validity range is specified with the tags <code>KM_TAG_ACTIVE_DATETIME</code>,
+<code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>, and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code>.
+The distinction between "origination" and "usage" is based on whether the key
+is being used to "originate" a new ciphertext/signature/etc., or to "use" an
+existing ciphertext/signature/etc.</p>
+
+<p>The <code>KM_TAG_ACTIVE_DATETIME</code>, <code>KM_TAG_ORIGINATION_EXPIRE_DATETIME</code>,
+and <code>KM_TAG_USAGE_EXPIRE_DATETIME</code> tags are optional. If the tags are absent, it is
+assumed that the key in
+question can always be used to decrypt/verify messages.</p>
+
+<p>Because wall-clock time is provided by the non-secure world, it's unlikely that
+the expiration-related tags will be in the hardware-enforced list. Hardware
+enforcement of expiry would require that the secure world somehow obtain
+trusted time and data, for example via a challenge response protocol with a
+trusted remote timeserver.</p>
+
+<h3 id=root_of_trust_binding>Root of trust binding</h3>
+
+<p>Keymaster allows keys to be bound to a root of trust, which is a bitstring
+provided to Keymaster during startup, preferably by the bootloader. If
+provided, this bitstring must be cryptographically bound to every key managed
+by Keymaster.</p>
+
+<p>The intent is for the bootloader to pass in the public key, used to verify the
+signature on the boot image, along with the verified boot state (locked or
+unlocked). If the public key is changed to allow a different system image to be
+used or if the verified boot state is changed, then none of the
+Keymaster-protected keys created by the previous system will be usable, unless
+the previous root of trust is restored and a system that is signed by that key
+is booted. The goal is to increase the value of the software-enforced key
+access controls by making it imposSTEM</code>sible for an attacker-installed operating
+system to use Keymaster keys.</p>
+
+<h3 id=standalone_keys>Standalone keys</h3>
+
+<p>Some Keymaster implementations may choose to store key material internally and
+return handles rather than encrypted key material. Or there may be other cases
+in which keys cannot be used until some other non-secure or secure world system
+component is available. The Keymaster 1.0 API allows the caller to request that
+a key be "standalone," via the <code>KM_TAG_STANDALONE</code> tag,
+meaning that no resources other than the blob and the running Keymaster
+system are required. The tags associated with a key may be inspected to see
+whether a key is standalone. At present, only two values are defined:</p>
+
+<ul>
+ <li><code>KM_BLOB_STANDALONE</code>
+ <li><code>KM_BLOB_REQUIRES_FILE_SYSTEM</code>
+</ul>
+
+<h3 id=velocity>Velocity</h3>
+
+<p>When it's created, the maximum usage velocity can be specified
+with <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code>.
+TrustZone implementations will refuse to perform cryptographic operations
+with that key if an operation was performed less
+than <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> seconds earlier.</p>
+
+<p>The simple approach to implementing velocity limits is a table of key IDs and
+last-use timestamps. This table will likely be of limited size, but must
+accommodate at least 16 entries. In the event that the table is full and no
+entries may be updated or discarded, Keymaster implementations must "fail
+safe," preferring to refuse all velocity-limited key operations until one of
+the entries expires. It is acceptable for all entries to expire upon reboot.</p>
+
+<p>Keys can also be limited to <em>n</em> uses per boot with <code>KM_TAG_USES_PER_BOOT</code>.
+This also requires a tracking table, which must accommodate at least four
+keys, and must also fail safe. Note that applications will be unable to create
+per-boot limited keys. This feature will not be exposed through keystore and
+will be reserved for system operations.</p>
+
+<h3 id=random_number_generator_re-seeding>Random number generator re-seeding</h3>
+
+<p>Because Keymaster must generate random numbers for key material and
+Initialization Vectors (IVs), and because hardware random number generators may
+not always be fully trustworthy, Keymaster provides an interface to allow the
+client to provide additional entropy which will be mixed into the random
+numbers generated.</p>
+
+<p>A hardware random-number generator should be used as the primary seed source,
+if available, and the seed data provided through the external API must not be
+the sole source of randomness used for number generation. Further, the mixing
+operation used must ensure that the random output is unpredictable if any one
+of the seed sources is unpredictable.</p>
diff --git a/src/security/authentication/km-implementer-ref.jd b/src/security/authentication/km-implementer-ref.jd
new file mode 100644
index 0000000..9c8c619
--- /dev/null
+++ b/src/security/authentication/km-implementer-ref.jd
@@ -0,0 +1,1229 @@
+page.title=Implementer's Reference
+@jd:body
+
+<!--
+ Copyright 2015 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>This page provides details to assist implementers of <a href="keymaster.html">Keymaster</a> HALs. It
+covers each tag and each function in the API.</p>
+
+<h2 id=authorization_tags>Authorization tags</h2>
+
+<p>Except as noted in the tag descriptions, all of the tags below are used during
+key generation to specify key characteristics.</p>
+
+<h3 id=km_tag_purpose>KM_TAG_PURPOSE</h3>
+
+<p>Specifies the set of purposes for which the key may be used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_PURPOSE_ENCRYPT = 0,
+ KM_PURPOSE_DECRYPT = 1,
+ KM_PURPOSE_SIGN = 2,
+ KM_PURPOSE_VERIFY = 3,
+} keymaster_purpose_t;
+</pre>
+
+<p>This tag is repeatable; keys may be generated with multiple values, although an
+operation has a single purpose. When the <a href="#begin">begin</a> function is called to
+start an operation, the purpose of the operation is
+specified. If the purpose specified to the operation is not authorized by the
+key, the operation must fail with <code>KM_ERROR_INCOMPATIBLE_PURPOSE</code>.</p>
+
+<h3 id=km_tag_algorithm>KM_TAG_ALGORITHM</h3>
+
+<p>Specifies the cryptographic algorithm with which the key is used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_ALGORITHM_RSA = 1,
+ KM_ALGORITHM_EC = 3,
+ KM_ALGORITHM_AES = 32,
+ KM_ALGORITHM_HMAC = 128,
+} keymaster_algorithm_t;
+</pre>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_key_size>KM_TAG_KEY_SIZE</h3>
+
+<p>Specifies the size, in bits, of the key, measuring in the normal way for the
+key's algorithm. For example, for RSA keys, <code>KM_TAG_KEY_SIZE</code> specifies
+the size of the public modulus. For AES keys it specifies the length
+of the secret key material.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_block_mode>KM_TAG_BLOCK_MODE</h3>
+
+<p>Specifies the block cipher mode(s) with which the key may be used. This tag is
+only relevant to AES keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_MODE_ECB = 1,
+ KM_MODE_CBC = 2,
+ KM_MODE_CTR = 3,
+ KM_MODE_GCM = 32,
+} keymaster_block_mode_t;
+</pre>
+
+<p>This tag is repeatable, and for AES key operations a mode must be specified in
+the <code>additional_params</code> argument of <a href="#begin">begin</a>. If the specified
+mode is not in the modes associated with the key, the
+operation must fail with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
+
+<h3 id=km_tag_digest>KM_TAG_DIGEST</h3>
+
+<p>Specifies the digest algorithms which may be used with the key to perform
+signing and verification operations. This tag is relevant to RSA, ECDSA and
+HMAC keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_DIGEST_NONE = 0,
+ KM_DIGEST_MD5 = 1,
+ KM_DIGEST_SHA1 = 2,
+ KM_DIGEST_SHA_2_224 = 3,
+ KM_DIGEST_SHA_2_256 = 4,
+ KM_DIGEST_SHA_2_384 = 5,
+ KM_DIGEST_SHA_2_512 = 6,
+}
+keymaster_digest_t;
+</pre>
+
+<p>This tag is repeatable. For signing and verification operations a digest must
+be specified in the <code>additional_params</code> argument of <a href="#begin">begin</a>.
+If the specified digest is not in the digests associated with the key, the
+operation must fail with <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.</p>
+
+<h3 id=km_tag_padding>KM_TAG_PADDING</h3>
+
+<p>Specifies the padding modes which may be used with the key. This tag is
+relevant to RSA and AES keys.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_PAD_NONE = 1,
+ KM_PAD_RSA_OAEP = 2,
+ KM_PAD_RSA_PSS = 3,
+ KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
+ KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
+ KM_PAD_PKCS7 = 64,
+} keymaster_padding_t;
+</pre>
+
+<p><code>KM_PAD_RSA_OAEP</code> and <code>KM_PAD_RSA_PKCS1_1_5_ENCRYPT</code> are used
+only for RSA encryption/decryption keys and specify RSA PKCS#1v2 OAEP
+padding and RSA PKCS#1 v1.5 randomized padding, respectively. <code>KM_PAD_RSA_PSS</code> and
+<code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> are used only for RSA signing/verification keys and
+specify RSA PKCS#1v2 PSS
+padding and RSA PKCS#1 v1.5 deterministic padding, respectively. Note also that
+the RSA PSS padding mode is incompatible with <a href="#km_tag_digest">KM_DIGEST_NONE</a>.</p>
+
+<p><code>KM_PAD_NONE</code> may be used with either RSA or AES keys. For AES keys,
+if <code>KM_PAD_NONE</code> is used with block mode ECB or CBC and the data to be encrypted
+or decrypted
+is not a multiple of the AES block size in length, the call to finish must fail
+with <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
+
+<p><code>KM_PAD_PKCS7</code> may only be used with AES keys, and only with ECB and CBC modes.</p>
+
+<p>This tag is repeatable. A padding mode must be specified in the call to
+<a href="#begin">begin</a>. If the specified mode is not authorized for the key,
+the operation must fail
+with <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code>.</p>
+
+<h3 id=km_tag_caller_nonce>KM_TAG_CALLER_NONCE</h3>
+
+<p>Specifies that the caller is allowed to provide a nonce for nonce-requiring
+operations.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is used only for AES keys, and is only relevant for CBC, CTR and GCM
+block modes. If the tag is not present, implementations should reject any
+operation which provides <a href="#km_tag_nonce">KM_TAG_NONCE</a> to <a href="#begin">begin</a>
+with <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_min_mac_length>KM_TAG_MIN_MAC_LENGTH</h3>
+
+<p>Required for HMAC keys and AES keys that support GCM mode, this tag specifies
+the minimum length of MAC that can be requested or verified with this key.</p>
+
+<p>This value is the minimum MAC length, in bits. It must be a multiple of 8. For
+HMAC keys, the value must be at least 64. For GCM keys it must be at least 96
+and must not exceed 128.</p>
+
+<h3 id=km_tag_rsa_public_exponent>KM_TAG_RSA_PUBLIC_EXPONENT</h3>
+
+<p>Specifies the value of the public exponent for an RSA key pair. This tag is
+relevant only to RSA keys, and required for all RSA keys.</p>
+
+<p>The value is a 64-bit unsigned integer that must satisfy the requirements of an
+RSA public exponent. Because it is specified by the caller and therefore cannot
+be chosen by the implementation, it must be a prime number. Trustlets are
+required to support the value 2^16+1. It is recommended that other reasonable
+values be supported, in particular the value 3. If no exponent is specified or
+if the specified exponent is not supported, key generation must fail
+with <code>KM_ERROR_INVALID_ARGUMENT</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_blob_usage_requirements>KM_TAG_BLOB_USAGE_REQUIREMENTS</h3>
+
+<p>Specifies the system environment conditions which must hold for the generated
+key to be used.</p>
+
+<p>Possible values are defined by the following enumeration:</p>
+
+<pre>
+typedef enum {
+ KM_BLOB_STANDALONE = 0,
+ KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
+} keymaster_key_blob_usage_requirements_t;
+</pre>
+
+<p>This tag may be specified during key generation to require that the key be
+usable in the specified condition, and must be returned with the key
+characteristics (from <a href="#generate_key">generate_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a>). If
+the caller specifies <code>KM_TAG_BLOB_USAGE_REQUIREMENTS</code> with
+value <code>KM_BLOB_STANDALONE</code> the trustlet must return a key blob
+which can be used without file system
+support. This is critical for devices with encrypted disks, where the file
+system may not be available until after a Keymaster key is used to decrypt the
+disk.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_bootloader_only>KM_TAG_BOOTLOADER_ONLY</h3>
+
+<p>Specifies that the key may only be used by the bootloader.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>Any attempt to use a key with <code>KM_TAG_BOOTLOADER_ONLY</code> from the
+Android system must fail with <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_active_datetime>KM_TAG_ACTIVE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key becomes active. Prior to this
+time, any attempt to use the key must fail with <code>KM_ERROR_KEY_NOT_YET_VALID</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_origination_expire_datetime>KM_TAG_ORIGINATION_EXPIRE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key expires for signing and encryption
+purposes. After this time, any attempt to use a key
+with <a href="#km_tag_purpose">KM_PURPOSE_SIGN</a> or
+<a href="#km_tag_purpose">KM_PURPOSE_ENCRYPT</a> provided
+to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_usage_expire_datetime>KM_TAG_USAGE_EXPIRE_DATETIME</h3>
+
+<p>Specifies the date and time at which the key expires for verification and
+decryption purposes. After this time, any attempt to use a key with
+<a href="#km_tag_purpose">KM_PURPOSE_VERIFY</a> or <a href="#km_tag_purpose">KM_PURPOSE DECRYPT</a>
+provided to <a href="#begin">begin</a> must fail with <code>KM_ERROR_KEY_EXPIRED</code>.</p>
+
+<p>The value is a 64-bit integer representing milliseconds since January 1, 1970.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_min_seconds_between_ops>KM_TAG_MIN_SECONDS_BETWEEN_OPS</h3>
+
+<p>Specifies the minimum amount of time that must elapse between allowed
+operations using a key. This can be used to rate-limit uses of keys in contexts
+where unlimited use may enable brute force attacks.</p>
+
+<p>The value is a 32-bit integer representing seconds between allowed operations.</p>
+
+<p>When a key with this tag is used in an operation, a timer should be started
+during the <a href="#finish">finish</a> or <a href="#abort">abort</a> call. Any
+call to <a href="#begin">begin</a> that is received before the timer indicates
+that the interval specified by <code>KM_TAG_MIN_SECONDS_BETWEEN_OPS</code> has
+elapsed must fail with <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. This
+requirement implies that a trustlet must keep a table of timers for keys
+with this tag. Because Keymaster memory is often limited, it is acceptable for
+this table to have a fixed maximum size and for Keymaster to fail operations
+which attempt to use keys with this tag when the table is full. At least 32
+in-use keys must be accommodated, and table slots must be aggressively reused
+when key minimum-usage intervals expire. If an operation fails because the
+table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_max_uses_per_boot>KM_TAG_MAX_USES_PER_BOOT</h3>
+
+<p>Specifies the maximum number of times that a key may be used between system
+reboots. This is another mechanism to rate-limit key use.</p>
+
+<p>The value is a 32-bit integer representing uses per boot.</p>
+
+<p>When a key with this tag is used in an operation, a key-associated counter
+should be incremented during the <a href="#begin">begin</a> call. After the key counter
+has exceeded this value, all subsequent attempts
+to use the key must fail with <code>KM_ERROR_MAX_OPS_EXCEEDED</code>, until the device is
+restarted. This requirement implies that a trustlet must
+keep a table of use counters for keys with this tag. Because Keymaster memory
+is often limited, it is acceptable for this table to have a fixed maximum size
+and for Keymaster to fail operations that attempt to use keys with this tag
+when the table is full. At least 16 keys must be accommodated. If an operation
+fails because the table is full, Keymaster should return <code>KM_ERROR_TOO_MANY_OPERATIONS</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_user_secure_id>KM_TAG_USER_SECURE_ID</h3>
+
+<p>Specifies that a key may only be used under a particular secure user
+authentication state. This tag is mutually exclusive
+with <a href="#km_tag_no_auth_required">KM_TAG_NO_AUTH_REQUIRED</a>.</p>
+
+<p>The value is a 64-bit integer specifying the authentication policy state value
+which must be present in an authentication token (provided to <a href="#begin">begin</a> with
+the <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a>) to authorize use of the key. Any
+call to <a href="#begin">begin</a> with a key with this tag that does not provide an
+authentication token, or provides an
+authentication token without a matching policy state value, must fail.</p>
+
+<p>This tag is repeatable. If any of the provided values matches any policy state
+value in the authentication token, the key is authorized for use. Otherwise the operation
+must fail with <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<h3 id=km_tag_no_auth_required>KM_TAG_NO_AUTH_REQUIRED</h3>
+
+<p>Specifies that no authentication is required to use this key. This tag is
+mutually exclusive with <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_user_auth_type>KM_TAG_USER_AUTH_TYPE</h3>
+
+<p>Specifies the types of user authenticators that may be used to authorize this
+key.</p>
+
+<p>The value is a 32-bit integer bitmask of values from the enumeration:</p>
+
+<pre>
+typedef enum {
+ HW_AUTH_NONE = 0,
+ HW_AUTH_PASSWORD = 1 << 0,
+ HW_AUTH_FINGERPRINT = 1 << 1,
+ // Additional entries should be powers of 2.
+ HW_AUTH_ANY = UINT32_MAX,
+} hw_authenticator_type_t;
+</pre>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_auth_timeout>KM_TAG_AUTH_TIMEOUT</h3>
+
+<p>Specifies the time in seconds for which the key is authorized for use, after
+authentication. If <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is present and this tag
+is not, then the key requires authentication for every
+usage (see <a href="#begin">begin</a> for the details of the authentication-per-operation flow).</p>
+
+<p>The value is a 32-bit integer specifying the time in seconds after a successful
+authentication of the user specified by <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> with
+the authentication method specified
+by <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> that the key can be used.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_all_applications>KM_TAG_ALL_APPLICATIONS</h3>
+
+<p>Reserved for future use.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_application_id>KM_TAG_APPLICATION_ID</h3>
+
+<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
+this tag specifies data that must be provided during all uses of the key. In
+particular, calls to <a href="#export_key">export_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a> must
+provide the same value in the <code>client_id</code> parameter, and
+calls to <a href="#begin">begin</a> must provide this tag and the
+same associated data as part of the <code>in_params</code> set. If the correct
+data is not provided the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_application_data>KM_TAG_APPLICATION_DATA</h3>
+
+<p>When provided to <a href="#generate_key">generate_key</a> or <a href="#import_key">import_key</a>,
+this tag specifies data that must be provided during all uses of the key. In
+particular, calls to <a href="#export_key">export_key</a> and
+<a href="#get_key_characteristics">get_key_characteristics</a> must
+provide the same value to the <code>client_id</code> parameter, and calls
+to <a href="#begin">begin</a> must provide this tag and the same associated
+data as part of the <code>in_params</code> set. If the correct data is not
+provided, the function must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_creation_datetime>KM_TAG_CREATION_DATETIME</h3>
+
+<p>Specifies the date and time the key was created, in milliseconds since January
+1, 1970. This tag is optional and informational only.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_origin>KM_TAG_ORIGIN</h3>
+
+<p>Specifies where the key was created, if known. This tag may not be specified
+during key generation or import, and must be added to the key characteristics
+by the trustlet.</p>
+
+<p>The possible values are defined in <code>keymaster_origin_t</code>:</p>
+
+<pre>
+typedef enum {
+ KM_ORIGIN_GENERATED = 0,
+ KM_ORIGIN_IMPORTED = 2,
+ KM_ORIGIN_UNKNOWN = 3,
+} keymaster_key_origin_t
+</pre>
+
+<p>The full meaning of the value depends not only on the value but on whether it's
+found in the hardware-enforced or software-enforced characteristics list.</p>
+
+<p><code>KM_ORIGIN_GENERATED</code> indicates that Keymaster generated the key.
+If in the hardware-enforced list,
+the key was generated in secure hardware and is permanently hardware-bound. If
+in the software-enforced list, the key was generated in SoftKeymaster and is
+not hardware-bound.</p>
+
+<p><code>KM_ORIGIN_IMPORTED</code> indicates that the key was generated outside
+of Keymaster and imported into
+Keymaster. If in the hardware-enforced list, it is permanently hardware-bound,
+although copies outside of secure hardware may exist. If in the
+software-enforces list, the key was imported into SoftKeymaster and is not
+hardware-bound.</p>
+
+<p><code>KM_ORIGIN_UNKNOWN</code> should only appear in the hardware-enforced list.
+It indicates that the key is
+hardware-bound, but it is not known whether the key was originally generated in
+secure hardware or was imported. This only occurs when keymaster0 hardware is
+being used to emulate keymaster1 services.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_rollback_resistant>KM_TAG_ROLLBACK_RESISTANT</h3>
+
+<p>Indicates that the key is rollback-resistant, meaning that when deleted
+by <a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
+the key is guaranteed to be permanently deleted and unusable. It's possible
+that keys without this tag could be deleted and then restored from backup.</p>
+
+<p>This tag is boolean, so the possible values are true (if the tag is present)
+and false (if the tag is not present).</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_root_of_trust>KM_TAG_ROOT_OF_TRUST</h3>
+
+<p>Specifies the "root of trust," the key used by verified boot to validate the
+operating system booted (if any). This tag is never provided to or returned
+from Keymaster in the key characteristics.</p>
+
+<h3 id=km_tag_associated_data>KM_TAG_ASSOCIATED_DATA</h3>
+
+<p>Provides "associated data" for AES-GCM encryption or decryption. This tag is
+provided to <a href="#update">update</a> and specifies data that is not
+encrypted/decrypted but is used in computing
+the GCM tag.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_nonce>KM_TAG_NONCE</h3>
+
+<p>Provides or returns a nonce or Initialization Vector (IV) for AES GCM, CBC or
+CTR encryption or decryption. This tag is provided to <a href="#begin">begin</a>
+during encryption and decryption operations. It may only be provided to <a href="#begin">begin</a>
+if the key has <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>. If not provided,
+an appropriate nonce or IV will be randomly generated by
+Keymaster and returned from begin.</p>
+
+<p>The value is a blob, an arbitrary-length array of bytes. Allowed lengths depend
+on the mode: GCM nonces are 12 bytes in length; CBC and CTR IVs are 16 bytes in
+length.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_auth_token>KM_TAG_AUTH_TOKEN</h3>
+
+<p>Provides an authentication token (see the Authentication page) to
+<a href="#begin">begin</a>, <a href="#update">update</a> or <a href="#finish">finish</a>,
+to prove user authentication for a key operation that requires
+it (key has <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>).</p>
+
+<p>The value is a blob which contains a <code>hw_auth_token_t</code> structure.</p>
+
+<p>This tag is not repeatable.</p>
+
+<h3 id=km_tag_mac_length>KM_TAG_MAC_LENGTH</h3>
+
+<p>Provides the requested length of a MAC or GCM authentication tag, in bits.</p>
+
+<p>The value is the MAC length in bits. It must be a multiple of 8 and must be at
+least as large as the value of <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
+associated with the key.</p>
+
+<h2 id=functions>Functions</h2>
+
+<h3 id=deprecated_functions>Deprecated functions</h3>
+
+<p>The following functions are in the <code>keymaster1_device_t</code> definition but
+should not be implemented. The function pointers should be set
+to <code>NULL</code>:</p>
+
+<ul>
+ <li><code>generate_keypair</code>
+ <li><code>import_keypair</code>
+ <li><code>get_keypair_public</code>
+ <li><code>delete_keypair</code>
+ <li><code>delete_all</code>
+ <li><code>sign_data</code>
+ <li><code>verify_data</code>
+</ul>
+
+<h3 id=general_implementation_guidelines>General implementation guidelines</h3>
+
+<p>The following guidelines apply to all functions in the API.</p>
+
+<h4 id=input_pointer_parameters>Input pointer parameters</h4>
+
+<p>Input pointer parameters that are not used for a given call may be <code>NULL</code>.
+The caller is not required to provide placeholders. For example, some key
+types and modes may not use any values from the <code>in_params</code> argument
+to <a href="#begin">begin</a>, so the caller may set <code>in_params</code>
+to <code>NULL</code> or provide an empty parameter set. It is also acceptable for the caller to
+provide unused parameters, and Keymaster methods should not issue errors.</p>
+
+<p>If a required input parameter is NULL, Keymaster methods should return
+<code>KM_ERROR_UNEXPECTED_NULL_POINTER</code>.</p>
+
+<h4 id=output_pointer_parameters>Output pointer parameters</h4>
+
+<p>Similar to input pointer parameters, unused output pointer parameters
+may be <code>NULL</code>. If a method needs to return data in an output
+parameter found to be <code>NULL</code>, it should return <code>KM_ERROR_OUTPUT_PARAMETER_NULL</code>.</p>
+
+<h4 id=api_misuse>API misuse</h4>
+
+<p>There are many ways that callers can make requests that don't make sense or are
+foolish but not technically wrong. Keymaster1 implementations are not required
+to fail in such cases or issue a diagnostic. Use of too-small keys,
+specification of irrelevant input parameters, reuse of IVs or nonces,
+generation of keys with no purposes (hence useless) and the like should not be
+diagnosed by implementations. Omission of required parameters, specification of
+invalid required parameters, and similar errors must be diagnosed.</p>
+
+<p>It is the responsibility of apps, the framework, and Android keystore to ensure
+that the calls to Keymaster modules are sensible and useful.</p>
+
+<h3 id=get_supported_algorithms>get_supported_algorithms</h3>
+
+<p>Returns the list of algorithms supported by the Keymaster hardware
+implementation. A software implementation must return an empty list; a hybrid
+implementation must return a list containing only the algorithms that are
+supported by hardware.</p>
+
+<p>Keymaster1 implementations must support RSA, EC, AES and HMAC.</p>
+
+<h3 id=get_supported_block_modes>get_supported_block_modes</h3>
+
+<p>Returns the list of AES block modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>For RSA, EC and HMAC, which are not block ciphers, the method must return an
+empty list for all valid purposes. Invalid purposes should cause the method to
+return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
+
+<p>Keymaster1 implementations must support ECB, CBC, CTR and GCM for AES
+encryption and decryption.</p>
+
+<h3 id=get_supported_padding_modes>get_supported_padding_modes</h3>
+
+<p>Returns the list of padding modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>HMAC and EC have no notion of padding so the method must return an empty list
+for all valid purposes. Invalid purposes should cause the method to return <code>KM_ERROR_INVALID_PURPOSE</code>.</p>
+
+<p>For RSA, keymaster1 implementations must support:</p>
+
+<ul>
+ <li>Unpadded encryption, decryption, signing and verification. For unpadded
+encryption and signing, if the message is shorter than the public modulus,
+implementations must left-pad it with zeros. For unpadded decryption and
+verification, the input length must match the public modulus size.
+ <li>PKCS#1 v1.5 encryption and signing padding modes
+ <li>PSS with a minimum salt length of 20
+ <li>OAEP
+</ul>
+
+<p>For AES in ECB and CBC modes, keymaster1 implementations must support no
+padding and PKCS#7-padding. CTR and GCM modes must support only no padding.</p>
+
+<h3 id=get_supported_digests>get_supported_digests</h3>
+
+<p>Returns the list of digest modes supported by the Keymaster hardware
+implementation for a specified algorithm and purpose.</p>
+
+<p>No AES modes support or require digesting, so the method must return an empty
+list for valid purposes.</p>
+
+<p>Keymaster1 implementations are allowed to implement a subset of the defined
+digests, but must provide SHA-256. It is strongly recommended that keymaster1
+implementations provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the
+full set of defined digests).</p>
+
+<h3 id=get_supported_import_formats>get_supported_import_formats</h3>
+
+<p>Returns the list of import formats supported by the Keymaster hardware
+implementation of a specified algorithm.</p>
+
+<p>Keymaster1 implementations must support the PKCS#8 format (without password
+protection) for importing RSA and EC key pairs, and must support RAW import of
+AES and HMAC key material.</p>
+
+<h3 id=get_supported_export_formats>get_supported_export_formats</h3>
+
+<p>Returns the list of export formats supported by the Keymaster hardware
+implementation of a specified algorithm.</p>
+
+<p>Keymaster1 implementations must support the X.509 format for exporting RSA and
+EC public keys. Export of private keys or asymmetric keys must not be
+supported.</p>
+
+<h3 id=add_rng_entropy>add_rng_entropy</h3>
+
+<p>Adds caller-provided entropy to the pool used by the Keymaster1 implementation
+for generating random numbers, for keys, IVs, etc.</p>
+
+<p>Keymaster1 implementations must <strong>securely</strong> mix the provided
+entropy into their pool, which must also contain
+internally-generated entropy from a hardware random number generator. Mixing
+must have the property that an attacker with complete control of either
+the <code>add_rng_entropy</code>-provided bits or the hardware-generated bits, but not both, cannot predict
+bits generated from the entropy pool with probability greater than ½.</p>
+
+<p>Keymaster1 implementations that attempt to estimate the entropy in their
+internal pool must assume that data provided by <code>add_rng_entropy</code> contains no entropy.</p>
+
+<h3 id=generate_key>generate_key</h3>
+
+<p>Generates a new cryptographic key, specifying associated authorizations, which
+will be permanently bound to the key. Keymaster1 implementations must make it
+impossible to use a key in any way inconsistent with the authorizations
+specified at generation time. With respect to authorizations that the secure
+hardware cannot enforce, the secure hardware's obligation is limited to
+ensuring that the unenforceable authorizations associated with the key cannot
+be modified, so that every call to <a href="#get_key_characteristics">get_key_characteristics</a>
+will return the original value. In addition, the characteristics returned by <code>generate_key</code>
+must allocate authorizations correctly between the hardware-enforced and
+software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
+for more details.</p>
+
+<p>The parameters that must be provided to <code>generate_key</code> depend on the type of key
+being generated. This section will summarize the
+required and allowed tags for each type of key. <a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>
+is always required, to specify the type.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>The following parameters are required when generating an RSA key.</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the size of the public
+ modulus, in bits. If omitted, the method must
+return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>. Values that must be supported are
+1024, 2048, 3072 and 4096. It is
+recommended to support all key sizes that are a multiple of 8.
+ <li><a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> specifies
+ the RSA public exponent value. If omitted, the method must
+ return <code>KM_ERROR_INVALID_ARGUMENT</code>.
+ Implementations must support the values 3 and 65537. It is recommended to
+support all prime values up to 2^64.
+</ul>
+
+<p>The following parameters are not required to generate an RSA key, but creating
+an RSA key without them will produce a key that is unusable.
+The <code>generate_key</code> function should not return an error if these parameters are omitted.</p>
+
+<ul>
+ <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> specifies allowed purposes.
+ All purposes must be supported for RSA keys, in
+any combination.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies digest algorithms that
+ may be used with the new key. Implementations
+that do not support all digest algorithms must accept key generation requests
+that include unsupported digests. The unsupported digests should be placed in
+the "software-enforced" list in the returned key characteristics. This is
+because the key will be usable with those other digests, but digesting will be
+performed in software. Then hardware will be called to perform the operation
+with <code>KM_DIGEST_NONE</code>.
+ <li><a href="#km_tag_padding">KM_TAG_PADDING</a> specifies the padding modes
+ that may be used with the new key. Implementations
+that do not support all digest algorithms must place <code>KM_PAD_RSA_PSS</code>
+and <code>KM_PAD_RSA_OAEP</code> in the software-enforced list of the key
+characteristics if any unsupported
+digest algorithms are specified.
+</ul>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required to generate an
+ECDSA key. It is used to select the EC group.
+Implementations must support values 224, 256, 384 and 521, which indicate the
+NIST p-224, p-256, p-384 and p521 curves, respectively.</p>
+
+<p><a href="#km_tag_digest">KM_TAG_DIGEST</a> is also needed for a useful ECDSA key,
+but is not required for generation.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>Only <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> is required when
+generating an AES key. If omitted, the method must return <code>KM_ERROR_UNSUPPORTED_KEY_SIZE</code>.
+Values that must be supported are 128 and 256. It is recommended to support
+192-bit AES keys.</p>
+
+<p>The following parameters are particularly relevant for AES keys, but not
+required to generate one:</p>
+
+<ul>
+ <li><code>KM_TAG_BLOCK_MODE</code> specifies the block modes with which the new key may be used.
+ <li><code>KM_TAG_PADDING</code> specifies the padding modes that may be used. This is only relevant for ECB
+and CBC modes.
+</ul>
+
+<p>If the GCM block mode is specified, then <a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a>
+must be provided. If omitted, the method must return
+<code>KM_ERROR_MISSING_MIN_MAC_LENGTH</code>. The value of the tag must be a multiple of 8 and must
+be at least 96 and no more than 128.</p>
+
+<h4 id=hmac_keys>HMAC keys</h4>
+
+<p>The following parameters are required for HMAC key generation:</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> specifies the key size in bits. Values
+ smaller than 64 and values that are not
+multiples of 8 must not be supported. All multiples of 8, from 64 to 512, must
+be supported. Larger values may be supported.
+ <li><a href="#km_tag_min_mac_length">KM_TAG_MIN_MAC_LENGTH</a> specifies the minimum length of
+ MACs that can be generated or verified with
+this key. The value must be a multiple of 8 and must be at least 64.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> specifies the digest algorithm for the key. Exactly
+ one digest must be
+specified, otherwise return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>. If the digest is not supported
+by the trustlet, return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.
+</ul>
+
+<h4 id=key_characteristics>Key characteristics</h4>
+
+<p>If the characteristics argument is non-NULL, <code>generate_key</code> must return the newly-generated
+key's characteristics divided appropriately
+into hardware-enforced and software-enforced lists. See <a href="#get_key_characteristics">get_key_characteristics</a>
+for a description of which characteristics go in which list. The returned
+characteristics must include all of the parameters specified to key generation,
+except <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> and
+<a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>.
+If these tags were included in the key parameters, they must be removed from
+the returned characteristics; it must not be possible to find their values by
+examining the returned key blob. However, they must be cryptographically bound
+to the key blob, so that if the correct values are not provided when the key is
+used, usage will fail. Similarly, <a href="#km_tag_root_of_trust">KM_TAG_ROOT_OF_TRUST</a> must
+be cryptographically bound to the key, but it may not be specified during
+key creation or import and must never be returned.</p>
+
+<p>In addition to the provided tags, the trustlet must also
+add <a href="#km_tag_origin">KM_TAG_ORIGIN</a>, with the value <code>KM_ORIGIN_GENERATED</code>,
+and if the key is rollback resistant, <a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a>.</p>
+
+<h4 id=rollback_resistance>Rollback resistance </h4>
+
+<p>Rollback resistance means that once a key is deleted with
+<a href="#delete_key">delete_key</a> or <a href="#delete_all_keys">delete_all_keys</a>,
+it is guaranteed by secure hardware never to be usable again. Implementations
+without rollback resistance will typically return generated or imported key
+material to the caller as a key blob, an encrypted and authenticated form. When
+keystore deletes the key blob, the key is gone, but an attacker who has
+previously managed to retrieve the key material can potentially restore it to
+the device.</p>
+
+<p>A key is rollback resistant if the secure hardware guarantees that deleted keys
+cannot be restored later. This is generally done by storing additional key
+metadata in a trusted location that cannot be manipulated by an attacker. On
+mobile devices, the mechanism used for this is usually Replay Protected Memory
+Blocks (RPMB). Because the number of keys that may be created is essentially
+unbounded and the trusted storage used for rollback resistance may be limited
+in size, it is required that this method succeed even if rollback resistance
+cannot be provided for the new key. In that case,
+<a href="#km_tag_rollback_resistant">KM_TAG_ROLLBACK_RESISTANT</a> should not be
+added to the key characteristics.</p>
+
+<h3 id=get_key_characteristics>get_key_characteristics</h3>
+
+<p>Returns parameters and authorizations associated with the provided key, divided
+into two sets: hardware-enforced and software-enforced. The description here
+applies equally to the key characteristics lists returned
+by <a href="#generate_key">generate_key</a> and <a href="#import_key">import_key</a>.</p>
+
+<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation
+or import, the same value must provided to
+this method in the <code>client_id</code> argument. Otherwise, the
+method must return <code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly,
+if <code>KM_TAG_APPLICATION_DATA </code>was provided during generation
+or import, the same value must be provided to
+this method in the <code>app_data</code> argument.</p>
+
+<p>The characteristics returned by this method completely describe the type and
+usage of the specified key.</p>
+
+<p>The general rule for deciding whether a given tag belongs in the
+hardware-enforced or software-enforced list is that if the meaning of the tag
+is fully assured by secure hardware, it is hardware-enforced. Otherwise, it's
+software enforced. Below is a list of specific tags whose correct allocation
+may be unclear:</p>
+
+<ul>
+ <li><a href="#km_tag_algorithm">KM_TAG_ALGORITHM</a>, <a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a>,
+ and <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> are
+ intrinsic properties of the key. For any key that is secured by hardware,
+these will be in the hardware-enforced list, because the statement that, for
+example, "This RSA key material is only used as an RSA key" is enforced by
+hardware because the hardware will use it in no other way and software has no
+access to the key material and cannot use it at all.
+ <li><a href="#km_tag_digest">KM_TAG_DIGEST</a> values that are supported by the
+ secure hardware are to be placed in the
+hardware-supported list. Unsupported digests go in the software-supported list.
+ <li><a href="#km_tag_padding">KM_TAG_PADDING</a> values generally go in the
+ hardware-supported list, but if there is a
+possibility that a specific padding mode may have to be performed by software,
+they go in the software-enforced list. Such a possibility arises for RSA keys
+that permit PSS or OAEP padding with digest algorithms that are not supported
+by the secure hardware.
+ <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> and
+ <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> are hardware-enforced
+ only if user authentication is hardware enforced. For
+that to be true, the Keymaster trustlet and the relevant authentication
+trustlet must both be secure and must share a secret HMAC key used to sign and
+validate authentication tokens. See the Authentication page for details.
+ <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a>,
+ <a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a>,
+ and <a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> tags
+ require access to a verifiably correct wall clock. Most secure hardware
+will only have access to time information provided by the non-secure OS, which
+means the tags are software-enforced.
+ <li><a href="#km_tag_origin">KM_TAG_ORIGIN</a> is always in the hardware list for
+ hardware-bound keys. Its presence in that
+list is the way higher layers determine that a key is hardware-backed.
+</ul>
+
+<h3 id=import_key>import_key</h3>
+
+<p>Imports key material into Keymaster hardware. Key definition parameters and
+output characteristics are handled the same as for <code>generate_key</code>,
+with the following exceptions:</p>
+
+<ul>
+ <li><a href="#km_tag_key_size">KM_TAG_KEY_SIZE</a> and
+ <a href="#km_tag_rsa_public_exponent">KM_TAG_RSA_PUBLIC_EXPONENT</a> (for RSA keys only)
+ are not required in the input parameters. If not provided,
+the trustlet must deduce the values from the provided key material and add
+appropriate tags and values to the key characteristics. If the parameters are
+provided, the trustlet must validate them against the key material. In the
+event of a mismatch, the method must return <code>KM_ERROR_IMPORT_PARAMETER_MISMATCH</code>.
+ <li>The returned <a href="#km_tag_origin">KM_TAG_ORIGIN</a> must have the
+ value <code>KM_ORIGIN_IMPORTED</code>.
+</ul>
+
+<h3 id=export_key>export_key</h3>
+
+<p>Exports a public key from a Keymaster RSA or EC key pair.</p>
+
+<p>If <code>KM_TAG_APPLICATION_ID</code> was provided during key generation or import,
+the same value must provided to
+this method in the <code>client_id</code> argument. Otherwise, the method must return
+<code>KM_ERROR_INVALID_KEY_BLOB</code>. Similarly, if <code>KM_TAG_APPLICATION_DATA</code>
+was provided during generation or import, the same value must be provided to
+this method in the <code>app_data</code> argument.</p>
+
+<h3 id=delete_key>delete_key</h3>
+
+<p>Deletes the provided key. This method is optional, and will likely be
+implemented only by Keymaster modules that provide rollback resistance.</p>
+
+<h3 id=delete_all_keys>delete_all_keys</h3>
+
+<p>Deletes all keys. This method is optional, and will likely be implemented only
+by Keymaster modules that provide rollback resistance.</p>
+
+<h3 id=begin>begin</h3>
+
+<p>Begins a cryptographic operation, using the specified key, for the specified
+purpose, with the specified parameters (as appropriate), and returns an
+operation handle which is used with <a href="#update">update</a> and <a href="#finish">finish</a> to complete the operation.</p>
+
+<p>If <a href="#km_tag_application_id">KM_TAG_APPLICATION_ID</a> or <a href="#km_tag_application_data">KM_TAG_APPLICATION_DATA</a>
+were specified during key generation or import, calls to begin must include
+those tags with the originally-specified values in the <code>in_params</code> argument to this method.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>During this method, the following key authorizations must be enforced by the
+trustlet if the implementation placed them in the "hardware-enforced"
+characteristics and if the operation is not a public key operation. Public key
+operations, meaning <code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>,
+with RSA or EC keys, must be allowed to succeed even if authorization
+requirements are not met.</p>
+
+<ul>
+ <li><a href="#km_tag_purpose">KM_TAG_PURPOSE</a> requires that the purpose specified
+ for this method match one of the purposes
+in the key authorizations, unless the requested operation is a public key
+operation, meaning that the key is RSA or EC and the purpose is <code>KM_PURPOSE_ENCRYPT</code>
+or <code>KM_PURPOSE_VERIFY</code>. Note that <code>KM_PURPOSE_ENCRYPT</code> is not valid for EC keys.
+Begin should return <code>KM_ERROR_UNSUPPORTED_PURPOSE</code> in that case.
+ <li><a href="#km_tag_active_datetime">KM_TAG_ACTIVE_DATETIME</a> requires comparison with a trusted
+ UTC time source. If the current date and
+time is prior to the tag value, the method must return <code>KM_ERROR_KEY_NOT_YET_VALID</code>.
+ <li><a href="#km_tag_origination_expire_datetime">KM_TAG_ORIGINATION_EXPIRE_DATETIME</a> requires
+ comparison with a trusted UTC time source. If the current date and
+time is later than the tag value and the purpose is <code>KM_PURPOSE_ENCRYPT</code> or <code>KM_PURPOSE_SIGN</code>,
+the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
+ <li><a href="#km_tag_usage_expire_datetime">KM_TAG_USAGE_EXPIRE_DATETIME</a> requires comparison with a
+ trusted UTC time source. If the current date and
+time is later than the tag value and the purpose is <code>KM_PURPOSE_DECRYPT</code> or <code>KM_PURPOSE_VERIFY</code>,
+the method must return <code>KM_ERROR_KEY_EXPIRED</code>.
+ <li><a href="#km_tag_min_seconds_between_ops">KM_TAG_MIN_SECONDS_BETWEEN_OPS</a> requires comparison with a
+ trusted relative timer indicating the last use of
+the key. If the last use time plus the tag value is less than the current time,
+the method must return <code>KM_ERROR_KEY_RATE_LIMIT_EXCEEDED</code>. See the tag description for
+important implementation requirements.
+ <li><a href="#km_tag_max_uses_per_boot">KM_TAG_MAX_USES_PER_BOOT</a> requires comparison against a
+ secure counter that tracks the uses of the key
+since boot time. If the count of previous uses exceeds the tag value, the
+method must return <code>KM_ERROR_KEY_MAX_OPS_EXCEEDED</code>.
+ <li><a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a> is enforced by this method only
+ if the key also has <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>. If the key has both,
+ then this method must have received a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in
+ <code>in_params</code> and that token must be valid, meaning that the HMAC field validates correctly.
+In addition, at least one of the <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_ID</a>
+values from the key must match at least one of the secure ID values in the
+token. Finally, the key must also have a <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a> and
+it must match the auth type in the token. If any of these requirements is
+not met, the method must return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.
+ <li><a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> allows the caller to specify a nonce
+ or initialization vector (IV). If the key
+does not have this tag but the caller provided <a href="#km_tag_nonce">KM_TAG_NONCE</a> to this method,
+<code>KM_ERROR_CALLER_NONCE_PROHIBITED</code> must be returned.
+ <li><a href="#km_tag_bootloader_only">KM_TAG_BOOTLOADER_ONLY</a> specifies that the key may only be
+ used by the bootloader. If this method is
+called with a bootloader-only key after the bootloader has finished executing,
+it must return <code>KM_ERROR_INVALID_KEY_BLOB</code>.
+</ul>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>All RSA key operations must specify exactly one padding mode in <code>in_params</code>. If
+unspecified or specified more than once, the method must return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
+
+<p>RSA signing and verification operations require a digest, as do RSA encryption
+and decryption operations with OAEP padding mode. For those cases, the caller
+must specify exactly one digest in <code>in_params</code>. If unspecified or specified more than once,
+the method must return <code>KM_ERROR_UNSUPPORTED_DIGEST</code>.</p>
+
+<p>Private key operations (<code>KM_PURPOSE_DECYPT</code> and <code>KM_PURPOSE_SIGN</code>) require
+authorization of digest and padding, which means that the specified
+values must be in the key authorizations. If not, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>
+or <code>KM_ERROR_INCOMPATIBLE_PADDING</code>, as appropriate. Public key operations
+(<code>KM_PURPOSE_ENCRYPT</code> and <code>KM_PURPOSE_VERIFY</code>) are permitted with
+unauthorized digest or padding.</p>
+
+<p>With the exception of <code>KM_PAD_NONE</code>, all RSA padding modes are applicable only to
+certain purposes. Specifically, <code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> and <code>KM_PAD_RSA_PSS</code>
+only support signing and verification, while <code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> and
+<code>KM_PAD_RSA_OAEP</code> only support encryption and decryption. The method must return
+<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code> if the specified mode does not support the specified purpose.</p>
+
+<p>There are some important interactions between padding modes and digests:</p>
+
+<ul>
+ <li><code>KM_PAD_NONE</code> indicates that a "raw" RSA operation will be performed. If signing or
+verifying, <code>KM_DIGEST_NONE </code>must be specified for the digest. No digest is required for unpadded encryption
+or decryption.
+ <li><code>KM_PAD_RSA_PKCS1_1_5_SIGN</code> padding requires a digest, which may be <code>KM_DIGEST_NONE.</code>
+ <li><code>KM_PAD_RSA_PKCS1_1_1_5_ENCRYPT</code> padding does not require a digest.
+ <li><code>KM_PAD_RSA_PSS</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
+ If <code>KM_DIGEST_NONE</code> is specified, the method must return
+ <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>. In addition, the
+ size of the RSA key must be at least 22 bytes larger than
+the output size of the digest. Otherwise, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+ <li><code>KM_PAD_RSA_OAEP</code> padding requires a digest, which may not be <code>KM_DIGEST_NONE</code>.
+ If <code>KM_DIGEST_NONE</code> is specified, the method must return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+</ul>
+
+<h4 id=ec_keys>EC keys</h4>
+
+<p>EC key operations must specify exactly one padding mode in <code>in_params</code>.
+If unspecified or specified more than once,
+return <code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>.</p>
+
+<p>Private key operations (<code>KM_PURPOSE_SIGN</code>) require authorization of the
+digest, which means that the specified value must be in the key authorizations.
+If not, return <code>KM_ERROR_INCOMPATIBLE_DIGEST</code>.
+Public key operations (<code>KM_PURPOSE_VERIFY</code>) are permitted with unauthorized digest or padding.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>AES key operations must specify exactly one block mode and one padding mode in <code>in_params</code>.
+If either value is unspecified or specified more than once, return <code>KM_ERROR_UNSUPPORTED_BLOCK_MODE</code> or
+<code>KM_ERROR_UNSUPPORTED_PADDING_MODE</code>. The specified modes must be authorized by the key.
+Otherwise, the method must
+return <code>KM_ERROR_INCOMPATIBLE_BLOCK_MODE</code> or <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_GCM</code>, <code>in_params</code> must specify <code>KM_TAG_MAC_LENGTH</code>, and the
+specified value must be a multiple of 8 and must not be greater than
+128, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations. For MAC lengths greater than 128 or non-multiples of
+8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_GCM</code> or <code>KM_MODE_CTR</code>, the specified padding mode must
+be <code>KM_PAD_NONE</code>. For <code>KM_MODE_ECB</code> or <code>KM_MODE_CBC</code>, the mode may
+be <code>KM_PAD_NONE</code> or <code>KM_PAD_PKCS7</code>. If the padding mode doesn't meet these
+requirements, return <code>KM_ERROR_INCOMPATIBLE_PADDING_MODE</code>.</p>
+
+<p>If the block mode is <code>KM_MODE_CBC</code>, <code>KM_MODE_CTR</code>, or <code>KM_MODE_GCM</code>, an initialization vector or nonce is needed.
+In most cases, callers should not
+provide an IV or nonce and the Keymaster implementation must generate a random
+IV or nonce and return it via <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>out_params</code>. CBC
+and CTR IVs are 16 bytes. GCM nonces are 12 bytes. If the key
+authorizations contain <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a>, then the caller may
+provide an IV/nonce with <a href="#km_tag_nonce">KM_TAG_NONCE</a> in <code>in_params</code>. If a
+nonce is provided when <a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is not authorized,
+return <code>KM_ERROR_CALLER_NONCE_PROHIBITED</code>. If a nonce is not provided when
+<a href="#km_tag_caller_nonce">KM_TAG_CALLER_NONCE</a> is authorized, generate a random IV/nonce.</p>
+
+<h4 id=hmac_keys>HMAC keys</h4>
+
+<p>HMAC key operations must specify <code>KM_TAG_MAC_LENGTH</code> in <code>in_params</code>.
+The specified value must be a multiple of 8 and must not be greater than the
+digest length, or less than the value of <code>KM_TAG_MIN_MAC_LENGTH</code> in the key authorizations.
+For MAC lengths greater than the digest length or
+non-multiples of 8, return <code>KM_ERROR_UNSUPPORTED_MAC_LENGTH</code>. For values less than
+the key's minimum length, return <code>KM_ERROR_INVALID_MAC_LENGTH</code>.</p>
+
+<h3 id=update>update</h3>
+
+<p>Provides data to process in an ongoing operation started with <a href="#begin">begin</a>.
+The operation is specified by the <code>operation_handle</code> parameter.</p>
+
+<p>To provide more flexibility for buffer handling, implementations of this method
+have the option of consuming less data than was provided. The caller is
+responsible for looping to feed the rest of the data in subsequent calls. The
+amount of input consumed must be returned in the <code>input_consumed</code> parameter.
+Implementations must always consume at least one byte, unless the
+operation cannot accept any more; if more than zero bytes are provided and zero
+bytes are consumed, callers will consider this an error and abort the
+operation.</p>
+
+<p>Implementations may also choose how much data to return, as a result of the
+update. This is only relevant for encryption and decryption operations, since
+signing and verification return no data until <a href="#finish">finish</a>. It is recommended
+to return data as early as possible, rather than buffer it.</p>
+
+<h4 id=error_handling>Error handling</h4>
+
+<p>If this method returns an error code other than <code>KM_ERROR_OK</code>, the operation is
+aborted and the operation handle must be invalidated. Any
+future use of the handle, with this method or <a href="#finish">finish</a> or <a href="#abort">abort</a>,
+must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception
+is the case where the key has:</p>
+
+<ul>
+ <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
+ <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
+</ul>
+
+<p>In this case, the key requires an authorization per operation, and the update
+method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
+The token must be valid (HMAC must verify) and it must contain a
+matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
+contain the operation handle of the current operation in the
+challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and
+<a href="#finish">finish</a>. The implementation need only validate the token once if it prefers.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept
+the entire block to be signed or verified in a single
+update. It may not consume only a portion of the block. It still must accept
+the data in multiple updates if the caller chooses to provide it that way,
+however. If the caller provides more data to sign than can be used (length of
+data exceeds RSA key size), return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>.</p>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>For signing and verification operations with <code>KM_DIGEST_NONE</code>, this method must accept the
+entire block to be signed or verified in a single
+update. This method may not consume only a portion of the block.</p>
+
+<p>However, this method still must accept the data in multiple updates if the
+caller chooses to provide it that way. If the caller provides more data to sign
+than can be used, the data should be silently truncated. (This differs from the
+handling of excess data provided in similar RSA operations. The reason for this
+is compatibility with legacy clients.)</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>AES GCM mode supports "associated authentication data," provided via the
+<a href="#km_tag_associated_data">KM_TAG_ASSOCIATED_DATA</a> tag in the <code>in_params</code> argument.
+The associated data may be provided in repeated calls (important if
+the data is too large to send in a single block) but must always precede data
+to be encrypted or decrypted. An update call may receive both associated data
+and data to encrypt/decrypt, but subsequent updates may not include associated
+data. If the caller provides associated data to an update call after a call
+that includes data to encrypt/decrypt, return <code>KM_ERROR_INVALID_TAG</code>.</p>
+
+<p>For GCM encryption, the tag is appended to the ciphertext by <a href="#finish">finish</a>.
+During decryption, the last <code>KM_TAG_MAC_LENGTH</code> bytes of the data provided to the last
+update call is the tag. Since a given
+invocation of <a href="#update">update</a> cannot know if it's the last invocation, it must process all but the tag
+length and buffer the possible tag data for processing during <a href="#finish">finish</a>.</p>
+
+<h3 id=finish>finish</h3>
+
+<p>Finished an ongoing operation started with <a href="#begin">begin</a>, processing all of the
+as-yet-unprocessed data provided by <a href="#update">update</a>(s).</p>
+
+<p>This method is the last one called in an operation, so all processed data must
+be returned.</p>
+
+<p>Whether it completes successfully or returns an error, this method finalizes
+the operation and therefore invalidates the provided operation handle. Any
+future use of the handle, with this method or <a href="#update">update</a> or
+<a href="#abort">abort</a>, must return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code>.</p>
+
+<p>Signing operations return the signature as the output. Verification operations
+accept the signature in the <code>signature</code> parameter, and return no output.</p>
+
+<h4 id=authorization_enforcement>Authorization enforcement</h4>
+
+<p>Key authorization enforcement is performed primarily in <a href="#begin">begin</a>. The one exception is the case where the key has:</p>
+
+<ul>
+ <li>One or more <a href="#km_tag_user_secure_id">KM_TAG_USER_SECURE_IDs</a>, and
+ <li>Does not have a <a href="#km_tag_auth_timeout">KM_TAG_AUTH_TIMEOUT</a>
+</ul>
+
+<p>In this case, the key requires an authorization per operation, and the update
+method must receive a <a href="#km_tag_auth_token">KM_TAG_AUTH_TOKEN</a> in the <code>in_params</code> argument.
+The token must be valid (HMAC must verify) and it must contain a
+matching secure user ID, must match the key's <a href="#km_tag_mac_length">KM_TAG_USER_AUTH_TYPE</a>, and must
+contain the operation handle of the current operation in the
+challenge field. If these requirements aren't met, return <code>KM_ERROR_KEY_USER_NOT_AUTHENTICATED</code>.</p>
+
+<p>The caller must provide the authentication token to every call to <a href="#update">update</a> and <a href="#finish">finish</a>.
+The implementation need only validate the token once if it prefers.</p>
+
+<h4 id=rsa_keys>RSA keys</h4>
+
+<p>Some additional requirements, depending on the padding mode:</p>
+
+<ul>
+ <li><strong>KM_PAD_NONE</strong>. For unpadded signing and encryption operations, if the provided data is
+shorter than the key, the data must be zero-padded on the left before
+signing/encryption. If the data is the same length as the key but numerically
+larger, return <code>KM_ERROR_INVALID_ARGUMENT</code>. For verification and decryption operations, the data must be exactly as long
+as the key. Otherwise, return <code>KM_ERROR_INVALID_INPUT_LENGTH.</code>
+ <li><strong>KM_PAD_RSA_PSS</strong>. For PSS-padded signature operations, the PSS salt must be at least 20 bytes
+in length and randomly-generated. The salt may be longer; the reference
+implementation uses maximally-sized salt. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
+<code>input_params</code> on <a href="#begin">begin</a> is used as the PSS digest algorithm, and SHA1 is used as the MGF1 digest
+algorithm.
+ <li><strong>KM_PAD_RSA_OAEP</strong>. The digest specified with <a href="#km_tag_digest">KM_TAG_DIGEST</a> in
+ <code>input_params</code> on <a href="#begin">begin</a> is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest
+algorithm.
+</ul>
+
+<h4 id=ecdsa_keys>ECDSA keys</h4>
+
+<p>If the data provided for unpadded signing or verification is too long, truncate
+it.</p>
+
+<h4 id=aes_keys>AES keys</h4>
+
+<p>Some additional requirements, depending on block mode:</p>
+
+<ul>
+ <li><strong>KM_MODE_ECB</strong> or <strong>KM_MODE_CBC</strong>. If padding is <code>KM_PAD_NONE</code> and the
+ data length is not a multiple of the AES block size, return <code>KM_ERROR_INVALID_INPUT_LENGTH</code>. If
+ padding is <code>KM_PAD_PKCS7</code>, pad the data per the PKCS#7 specification. Note that PKCS#7 requires that if
+the data is a multiple of the block length, an additional padding block must be
+added.
+ <li><strong>KM_MODE_GCM</strong>. During encryption, after processing all plaintext, compute the
+ tag (<a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes) and append it to the returned ciphertext.
+ During decryption, process
+the last <a href="#km_tag_mac_length">KM_TAG_MAC_LENGTH</a> bytes as the tag. If tag verification fails,
+return <code>KM_ERROR_VERIFICATION_FAILED</code>.
+</ul>
+
+<h3 id=abort>abort</h3>
+
+<p>Aborts the in-progress operation. After the call to abort, return <code>KM_ERROR_INVALID_OPERATION_HANDLE</code> for
+any subsequent use of the provided operation handle with <a href="#update">update</a>,
+<a href="#finish">finish</a>, or <a href="#abort">abort</a>.</p>
diff --git a/src/security/encryption/index.jd b/src/security/encryption/index.jd
new file mode 100644
index 0000000..f7bcc3b
--- /dev/null
+++ b/src/security/encryption/index.jd
@@ -0,0 +1,518 @@
+page.title=Full Disk Encryption
+@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=what_is_encryption>What is full disk encryption?</h2>
+
+<p>Full disk encryption is the process of encoding all user data on an Android device using an
+encrypted key. Once a device is encrypted, all user-created data is
+automatically encrypted before committing it to disk and all reads
+automatically decrypt data before returning it to the calling process.</p>
+
+<h2 id=what_we’ve_added_for_android_l>What we’ve added for Android 5.0</h2>
+
+<ul>
+ <li>Created fast encryption, which only encrypts used blocks on the data partition
+to avoid first boot taking a long time. Only ext4 and f2fs filesystems
+currently support fast encryption.
+ <li>Added the <code>forceencrypt</code> flag to encrypt on first boot.
+ <li>Added support for patterns and encryption without a password.
+ <li>Added hardware-backed storage of the encryption key using Trusted
+ Execution Environment’s (TEE) signing capability (such as in a TrustZone).
+ See <a href="#storing_the_encrypted_key">Storing the encrypted key</a> for more
+ details.
+</ul>
+
+<p class="caution"><strong>Caution:</strong> Devices upgraded to Android 5.0 and then
+encrypted may be returned to an unencrypted state by factory data reset. New Android 5.0
+devices encrypted at first boot cannot be returned to an unencrypted state.</p>
+
+<h2 id=how_android_encryption_works>How Android full disk encryption works</h2>
+
+<p>Android full disk encryption is based on <code>dm-crypt</code>, which is a kernel
+feature that works at the block device layer. Because of
+this, encryption works with Embedded MultiMediaCard<strong> (</strong>eMMC) and
+similar flash devices that present themselves to the kernel as block
+devices. Encryption is not possible with YAFFS, which talks directly to a raw
+NAND flash chip. </p>
+
+<p>The encryption algorithm is 128 Advanced Encryption Standard (AES) with
+cipher-block chaining (CBC) and ESSIV:SHA256. The master key is encrypted with
+128-bit AES via calls to the OpenSSL library. You must use 128 bits or more for
+the key (with 256 being optional). </p>
+
+<p class="note"><strong>Note:</strong> OEMs can use 128-bit or higher to encrypt the master key.</p>
+
+<p>In the Android 5.0 release, there are four kinds of encryption states: </p>
+
+<ul>
+ <li>default
+ <li>PIN
+ <li>password
+ <li>pattern
+</ul>
+
+<p>Upon first boot, the device creates a randomly generated 128-bit master key
+and then hashes it with a default password and stored salt. The default password is: "default_password"
+However, the resultant hash is also signed through a TEE (such as TrustZone),
+which uses a hash of the signature to encrypt the master key.</p>
+
+<p>You can find the default password defined in the Android Open Source Project <a
+href="https://android.googlesource.com/platform/system/vold/+/master/cryptfs.c">cryptfs.c</a>
+file.</p>
+
+<p>When the user sets the PIN/pass or password on the device, only the 128-bit key
+is re-encrypted and stored. (ie. user PIN/pass/pattern changes do NOT cause
+re-encryption of userdata.) </p>
+
+<p>Encryption is managed by <code>init</code> and <code>vold</code>. <code>init</code> calls <code>vold</code>, and vold sets properties to trigger events in init. Other parts of the system
+also look at the properties to conduct tasks such as report status, ask for a
+password, or prompt to factory reset in the case of a fatal error. To invoke
+encryption features in <code>vold</code>, the system uses the command line tool <code>vdc</code>’s <code>cryptfs</code> commands: <code>checkpw</code>, <code>restart</code>, <code>enablecrypto</code>, <code>changepw</code>, <code>cryptocomplete</code>, <code>verifypw</code>, <code>setfield</code>, <code>getfield</code>, <code>mountdefaultencrypted</code>, <code>getpwtype</code>, <code>getpw</code>, and <code>clearpw</code>.</p>
+
+<p>In order to encrypt, decrypt or wipe <code>/data</code>, <code>/data</code> must not be mounted. However, in order to show any user interface (UI), the
+framework must start and the framework requires <code>/data</code> to run. To resolve this conundrum, a temporary filesystem is mounted on <code>/data</code>. This allows Android to prompt for passwords, show progress, or suggest a data
+wipe as needed. It does impose the limitation that in order to switch from the
+temporary filesystem to the true <code>/data</code> filesystem, the system must stop every process with open files on the
+temporary filesystem and restart those processes on the real <code>/data</code> filesystem. To do this, all services must be in one of three groups: <code>core</code>, <code>main</code>, and <code>late_start</code>.</p>
+
+<ul>
+ <li><code>core</code>: Never shut down after starting.
+ <li><code>main</code>: Shut down and then restart after the disk password is entered.
+ <li><code>late_start</code>: Does not start until after <code>/data</code> has been decrypted and mounted.
+</ul>
+
+<p>To trigger these actions, the <code>vold.decrypt</code> property is set to <a href="https://android.googlesource.com/platform/system/vold/+/master/cryptfs.c">various strings</a>. To kill and restart services, the <code>init</code> commands are:</p>
+
+<ul>
+ <li><code>class_reset</code>: Stops a service but allows it to be restarted with class_start.
+ <li><code>class_start</code>: Restarts a service.
+ <li><code>class_stop</code>: Stops a service and adds a <code>SVC_DISABLED</code> flag. Stopped services do not respond to <code>class_start</code>.
+</ul>
+
+<h2 id=flows>Flows</h2>
+
+<p>There are four flows for an encrypted device. A device is encrypted just once
+and then follows a normal boot flow. </p>
+
+<ul>
+ <li>Encrypt a previously unencrypted device:
+ <ul>
+ <li>Encrypt a new device with <code>forceencrypt</code>: Mandatory encryption at first boot (starting in Android L).
+ <li>Encrypt an existing device: User-initiated encryption (Android K and earlier).
+ </ul>
+ <li>Boot an encrypted device:
+ <ul>
+ <li>Starting an encrypted device with no password: Booting an encrypted device that
+has no set password (relevant for devices running Android 5.0 and later).
+ <li> Starting an encrypted device with a password: Booting an encrypted device that
+has a set password.
+ </ul>
+</ul>
+
+<p>In addition to these flows, the device can also fail to encrypt <code>/data</code>. Each of the flows are explained in detail below.</p>
+
+<h3 id=encrypt_a_new_device_with_forceencrypt>Encrypt a new device with /forceencrypt</h3>
+
+<p>This is the normal first boot for an Android 5.0 device. </p>
+
+<ol>
+ <li><strong>Detect unencrypted filesystem with <code>/forceencrypt</code> flag</strong>
+
+<p>
+<code>/data</code> is not encrypted but needs to be because <code>/forceencrypt</code> mandates it.
+Unmount <code>/data</code>.</p>
+
+ <li><strong>Start encrypting <code>/data</code></strong>
+
+<p><code>vold.decrypt = "trigger_encryption"</code> triggers <code>init.rc</code>, which will cause <code>vold</code> to encrypt <code>/data</code> with no password. (None is set because this should be a new device.)</p>
+
+
+ <li><strong>Mount tmpfs</strong>
+
+
+<p><code>vold</code> mounts a tmpfs <code>/data</code> (using the tmpfs options from
+<code>ro.crypto.tmpfs_options</code>) and sets the property <code>vold.encrypt_progress</code> to 0.
+<code>vold</code> prepepares the tmpfs <code>/data</code> for booting an encrypted system and sets the
+property <code>vold.decrypt</code> to: <code>trigger_restart_min_framework</code>
+</p>
+
+ <li><strong>Bring up framework to show progress</strong>
+
+
+<p>Because the device has virtually no data to encrypt, the progress bar will
+often not actually appear because encryption happens so quickly. See <a href="#encrypt_an_existing_device">Encrypt an existing device</a> for more details about the progress UI. </p>
+
+ <li><strong>When <code>/data</code> is encrypted, take down the framework</strong>
+
+<p><code>vold</code> sets <code>vold.decrypt</code> to
+<code>trigger_default_encryption</code> which starts the
+<code>defaultcrypto</code> service. (This starts the flow below for mounting a
+default encrypted userdata.) <code>trigger_default_encryption</code> checks the
+encryption type to see if <code>/data</code> is encrypted with or without a
+password. Because Android 5.0 devices are encrypted on first boot, there should
+be no password set; therefore we decrypt and mount <code>/data</code>.</p>
+
+ <li><strong>Mount <code>/data</code></strong>
+
+<p><code>init</code> then mounts <code>/data</code> on a tmpfs RAMDisk using parameters it picks up from <code>ro.crypto.tmpfs_options</code>, which is set in <code>init.rc</code>.</p>
+
+ <li><strong>Start framework</strong>
+
+<p>Set <code>vold</code> to <code>trigger_restart_framework</code>, which continues the usual boot process.</p>
+</ol>
+
+<h3 id=encrypt_an_existing_device>Encrypt an existing device</h3>
+
+<p>This is what happens when you encrypt an unencrypted Android K or earlier
+device that has been migrated to L. Note that this is the same flow as used in
+K.</p>
+
+<p>This process is user-initiated and is referred to as “inplace encryption” in
+the code. When a user selects to encrypt a device, the UI makes sure the
+battery is fully charged and the AC adapter is plugged in so there is enough
+power to finish the encryption process.</p>
+
+<p class="warning"><strong>Warning:</strong> If the device runs out of power and shuts down before it has finished
+encrypting, file data is left in a partially encrypted state. The device must
+be factory reset and all data is lost.</p>
+
+<p>To enable inplace encryption, <code>vold</code> starts a loop to read each sector of the real block device and then write it
+to the crypto block device. <code>vold</code> checks to see if a sector is in use before reading and writing it, which makes
+encryption much faster on a new device that has little to no data. </p>
+
+<p><strong>State of device</strong>: Set <code>ro.crypto.state = "unencrypted"</code> and execute the <code>on nonencrypted</code> <code>init</code> trigger to continue booting.</p>
+
+<ol>
+ <li><strong>Check password</strong>
+
+<p>The UI calls <code>vold</code> with the command <code>cryptfs enablecrypto inplace</code> where <code>passwd</code> is the user's lock screen password.</p>
+
+ <li><strong>Take down the framework</strong>
+
+<p><code>vold</code> checks for errors, returns -1 if it can't encrypt, and prints a reason in the
+log. If it can encrypt, it sets the property <code>vold.decrypt</code> to <code>trigger_shutdown_framework</code>. This causes <code>init.rc</code> to stop services in the classes <code>late_start</code> and <code>main</code>. </p>
+
+ <li><strong>Unmount <code>/data</code></strong>
+
+<p><code>vold</code> unmounts <code>/mnt/sdcard</code> and then <code>/data</code>.</p>
+
+ <li><strong>Start encrypting <code>/data</code></strong>
+
+<p><code>vold</code> then sets up the crypto mapping, which creates a virtual crypto block device
+that maps onto the real block device but encrypts each sector as it is written,
+and decrypts each sector as it is read. <code>vold</code> then creates and writes out the crypto metadata.</p>
+
+ <li><strong>While it’s encrypting, mount tmpfs</strong>
+
+<p><code>vold</code> mounts a tmpfs <code>/data</code> (using the tmpfs options from <code>ro.crypto.tmpfs_options</code>) and sets the property <code>vold.encrypt_progress</code> to 0. <code>vold</code> prepares the tmpfs <code>/data</code> for booting an encrypted system and sets the property <code>vold.decrypt</code> to: <code>trigger_restart_min_framework</code> </p>
+
+ <li><strong>Bring up framework to show progress</strong>
+
+<p><code>trigger_restart_min_framework </code>causes <code>init.rc</code> to start the <code>main</code> class of services. When the framework sees that <code>vold.encrypt_progress</code> is set to 0, it brings up the progress bar UI, which queries that property
+every five seconds and updates a progress bar. The encryption loop updates <code>vold.encrypt_progress</code> every time it encrypts another percent of the partition. </p>
+
+ <li><strong>When<code> /data</code> is encrypted, reboot</strong>
+
+<p>When <code>/data</code> is successfully encrypted, <code>vold</code> clears the flag <code>ENCRYPTION_IN_PROGRESS</code> in the metadata and reboots the system. </p>
+
+<p> If the reboot fails for some reason, <code>vold</code> sets the property <code>vold.encrypt_progress</code> to <code>error_reboot_failed</code> and the UI should display a message asking the user to press a button to
+reboot. This is not expected to ever occur.</p>
+</ol>
+
+<h3 id=starting_an_encrypted_device_with_default_encryption>Starting an encrypted device with default encryption</h3>
+
+<p>This is what happens when you boot up an encrypted device with no password.
+Because Android 5.0 devices are encrypted on first boot, there should be no set
+password and therefore this is the <em>default encryption</em> state.</p>
+
+<ol>
+ <li><strong>Detect encrypted <code>/data</code> with no password</strong>
+
+<p>Detect that the Android device is encrypted because <code>/data</code>
+cannot be mounted and one of the flags <code>encryptable</code> or
+<code>forceencrypt</code> is set.</p>
+
+<p><code>vold</code> sets <code>vold.decrypt</code> to <code>trigger_default_encryption</code>, which starts the <code>defaultcrypto</code> service. <code>trigger_default_encryption</code> checks the encryption type to see if <code>/data</code> is encrypted with or without a password. </p>
+
+ <li><strong>Decrypt /data</strong>
+
+<p>Creates the <code>dm-crypt</code> device over the block device so the device is ready for use.</p>
+
+ <li><strong>Mount /data</strong>
+
+<p><code>vold</code> then mounts the decrypted real <code>/data </code>partition and then prepares the new partition. It sets the property <code>vold.post_fs_data_done</code> to 0 and then sets <code>vold.decrypt</code> to <code>trigger_post_fs_data</code>. This causes <code>init.rc</code> to run its <code>post-fs-data</code> commands. They will create any necessary directories or links and then set <code>vold.post_fs_data_done</code> to 1.</p>
+
+<p>Once <code>vold</code> sees the 1 in that property, it sets the property <code>vold.decrypt</code> to: <code>trigger_restart_framework.</code> This causes <code>init.rc</code> to start services in class <code>main</code> again and also start services in class <code>late_start</code> for the first time since boot.</p>
+
+ <li><strong>Start framework</strong>
+
+<p>Now the framework boots all its services using the decrypted <code>/data</code>, and the system is ready for use.</p>
+</ol>
+
+<h3 id=starting_an_encrypted_device_without_default_encryption>Starting an encrypted device without default encryption</h3>
+
+<p>This is what happens when you boot up an encrypted device that has a set
+password. The device’s password can be a pin, pattern, or password. </p>
+
+<ol>
+ <li><strong>Detect encrypted device with a password</strong>
+
+<p>Detect that the Android device is encrypted because the flag <code>ro.crypto.state = "encrypted"</code></p>
+
+<p><code>vold</code> sets <code>vold.decrypt</code> to <code>trigger_restart_min_framework</code> because <code>/data</code> is encrypted with a password.</p>
+
+ <li><strong>Mount tmpfs</strong>
+
+<p><code>init</code> sets five properties to save the initial mount options given for <code>/data</code> with parameters passed from <code>init.rc</code>. <code>vold</code> uses these properties to set up the crypto mapping:</p>
+
+<ol>
+ <li><code>ro.crypto.fs_type</code>
+ <li><code>ro.crypto.fs_real_blkdev</code>
+ <li><code>ro.crypto.fs_mnt_point</code>
+ <li><code>ro.crypto.fs_options</code>
+ <li><code>ro.crypto.fs_flags </code>(ASCII 8-digit hex number preceded by 0x)
+ </ol>
+
+ <li><strong>Start framework to prompt for password</strong>
+
+<p>The framework starts up and sees that <code>vold.decrypt</code> is set to <code>trigger_restart_min_framework</code>. This tells the framework that it is booting on a tmpfs <code>/data</code> disk and it needs to get the user password.</p>
+
+<p>First, however, it needs to make sure that the disk was properly encrypted. It
+sends the command <code>cryptfs cryptocomplete</code> to <code>vold</code>. <code>vold</code> returns 0 if encryption was completed successfully, -1 on internal error, or
+-2 if encryption was not completed successfully. <code>vold</code> determines this by looking in the crypto metadata for the <code>CRYPTO_ENCRYPTION_IN_PROGRESS</code> flag. If it's set, the encryption process was interrupted, and there is no
+usable data on the device. If <code>vold</code> returns an error, the UI should display a message to the user to reboot and
+factory reset the device, and give the user a button to press to do so.</p>
+
+ <li><strong>Decrypt data with password</strong>
+
+<p>Once <code>cryptfs cryptocomplete</code> is successful, the framework displays a UI asking for the disk password. The
+UI checks the password by sending the command <code>cryptfs checkpw</code> to <code>vold</code>. If the password is correct (which is determined by successfully mounting the
+decrypted <code>/data</code> at a temporary location, then unmounting it), <code>vold</code> saves the name of the decrypted block device in the property <code>ro.crypto.fs_crypto_blkdev</code> and returns status 0 to the UI. If the password is incorrect, it returns -1 to
+the UI.</p>
+
+ <li><strong>Stop framework</strong>
+
+<p>The UI puts up a crypto boot graphic and then calls <code>vold</code> with the command <code>cryptfs restart</code>. <code>vold</code> sets the property <code>vold.decrypt</code> to <code>trigger_reset_main</code>, which causes <code>init.rc</code> to do <code>class_reset main</code>. This stops all services in the main class, which allows the tmpfs <code>/data</code> to be unmounted. </p>
+
+ <li><strong>Mount <code>/data</code></strong>
+
+<p><code>vold</code> then mounts the decrypted real <code>/data </code>partition and prepares the new partition (which may never have been prepared if
+it was encrypted with the wipe option, which is not supported on first
+release). It sets the property <code>vold.post_fs_data_done</code> to 0 and then sets <code>vold.decrypt</code> to <code>trigger_post_fs_data</code>. This causes <code>init.rc</code> to run its <code>post-fs-data</code> commands. They will create any necessary directories or links and then set <code>vold.post_fs_data_done</code> to 1. Once <code>vold</code> sees the 1 in that property, it sets the property <code>vold.decrypt</code> to <code>trigger_restart_framework</code>. This causes <code>init.rc</code> to start services in class <code>main</code> again and also start services in class <code>late_start</code> for the first time since boot.</p>
+
+ <li><strong>Start full framework</strong>
+
+<p>Now the framework boots all its services using the decrypted <code>/data</code> filesystem, and the system is ready for use.</p>
+</ol>
+
+<h3 id=failure>Failure</h3>
+
+<p>A device that fails to decrypt might be awry for a few reasons. The device
+starts with the normal series of steps to boot:</p>
+
+<ol>
+ <li>Detect encrypted device with a password
+ <li>Mount tmpfs
+ <li>Start framework to prompt for password
+</ol>
+
+<p>But after the framework opens, the device can encounter some errors:</p>
+
+<ul>
+ <li>Password matches but cannot decrypt data
+ <li>User enters wrong password 30 times
+</ul>
+
+<p>If these errors are not resolved, <strong>prompt user to factory wipe</strong>:</p>
+
+<p>If <code>vold</code> detects an error during the encryption process, and if no data has been
+destroyed yet and the framework is up, <code>vold</code> sets the property <code>vold.encrypt_progress </code>to <code>error_not_encrypted</code>. The UI prompts the user to reboot and alerts them the encryption process
+never started. If the error occurs after the framework has been torn down, but
+before the progress bar UI is up, <code>vold</code> will reboot the system. If the reboot fails, it sets <code>vold.encrypt_progress</code> to <code>error_shutting_down</code> and returns -1; but there will not be anything to catch the error. This is not
+expected to happen.</p>
+
+<p>If <code>vold</code> detects an error during the encryption process, it sets <code>vold.encrypt_progress</code> to <code>error_partially_encrypted</code> and returns -1. The UI should then display a message saying the encryption
+failed and provide a button for the user to factory reset the device. </p>
+
+<h2 id=storing_the_encrypted_key>Storing the encrypted key</h2>
+
+<p>The encrypted key is stored in the crypto metadata. Hardware backing is implemented by using Trusted Execution Environment’s (TEE) signing capability.
+Previously, we encrypted the master key with a key generated by applying scrypt to the user's password and the stored salt. In order to make the key resilient
+against off-box attacks, we extend this algorithm by signing the resultant key with a stored TEE key. The resultant signature is then turned into an appropriate length key by one more application of scrypt. This key is then used to encrypt and decrypt the master key. To store this key:</p>
+
+<ol>
+ <li>Generate random 16-byte disk encryption key (DEK) and 16-byte salt.
+ <li>Apply scrypt to the user password and the salt to produce 32-byte intermediate
+key 1 (IK1).
+ <li>Pad IK1 with zero bytes to the size of the hardware-bound private key (HBK).
+Specifically, we pad as: 00 || IK1 || 00..00; one zero byte, 32 IK1 bytes, 223
+zero bytes.
+ <li>Sign padded IK1 with HBK to produce 256-byte IK2.
+ <li>Apply scrypt to IK2 and salt (same salt as step 2) to produce 32-byte IK3.
+ <li>Use the first 16 bytes of IK3 as KEK and the last 16 bytes as IV.
+ <li>Encrypt DEK with AES_CBC, with key KEK, and initialization vector IV.
+</ol>
+
+<h2 id=changing_the_password>Changing the password</h2>
+
+<p>When a user elects to change or remove their password in settings, the UI sends
+the command <code>cryptfs changepw</code> to <code>vold</code>, and <code>vold</code> re-encrypts the disk master key with the new password.</p>
+
+<h2 id=encryption_properties>Encryption properties</h2>
+
+<p><code>vold</code> and <code>init</code> communicate with each other by setting properties. Here is a list of available
+properties for encryption.</p>
+
+<h3 id=vold_properties>Vold properties </h3>
+
+<table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_encryption</code></td>
+ <td>Encrypt the drive with no
+ password.</td>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_default_encryption</code></td>
+ <td>Check the drive to see if it is encrypted with no password.
+If it is, decrypt and mount it,
+else set <code>vold.decrypt</code> to trigger_restart_min_framework.</td>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_reset_main</code></td>
+ <td>Set by vold to shutdown the UI asking for the disk password.</td>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_post_fs_data</code></td>
+ <td> Set by vold to prep /data with necessary directories, et al.</td>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_restart_framework</code></td>
+ <td>Set by vold to start the real framework and all services.</td>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_shutdown_framework</code></td>
+ <td>Set by vold to shutdown the full framework to start encryption.</td>
+ </tr>
+ <tr>
+ <td><code>vold.decrypt trigger_restart_min_framework</code></td>
+ <td>Set by vold to start the
+progress bar UI for encryption or
+prompt for password, depending on
+the value of <code>ro.crypto.state</code>.</td>
+ </tr>
+ <tr>
+ <td><code>vold.encrypt_progress</code></td>
+ <td>When the framework starts up,
+if this property is set, enter
+the progress bar UI mode.</td>
+ </tr>
+ <tr>
+ <td><code>vold.encrypt_progress 0 to 100</code></td>
+ <td>The progress bar UI should
+display the percentage value set.</td>
+ </tr>
+ <tr>
+ <td><code>vold.encrypt_progress error_partially_encrypted</code></td>
+ <td>The progress bar UI should display a message that the encryption failed, and
+give the user an option to
+factory reset the device.</td>
+ </tr>
+ <tr>
+ <td><code>vold.encrypt_progress error_reboot_failed</code></td>
+ <td>The progress bar UI should
+display a message saying encryption completed, and give the user a button to reboot the device. This error is not expected to happen.</td>
+ </tr>
+ <tr>
+ <td><code>vold.encrypt_progress error_not_encrypted</code></td>
+ <td>The progress bar UI should
+display a message saying an error
+occurred, no data was encrypted or
+lost, and give the user a button to reboot the system.</td>
+ </tr>
+ <tr>
+ <td><code>vold.encrypt_progress error_shutting_down</code></td>
+ <td>The progress bar UI is not running, so it is unclear who will respond to this error. And it should never happen anyway.</td>
+ </tr>
+ <tr>
+ <td><code>vold.post_fs_data_done 0</code></td>
+ <td>Set by <code>vold</code> just before setting <code>vold.decrypt</code> to <code>trigger_post_fs_data</code>.</td>
+ </tr>
+ <tr>
+ <td><code>vold.post_fs_data_done 1</code></td>
+ <td>Set by <code>init.rc</code> or
+ <code>init.rc</code> just after finishing the task <code>post-fs-data</code>.</td>
+ </tr>
+</table>
+<h3 id=init_properties>init properties</h3>
+
+<table>
+ <tr>
+ <th>Property</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>ro.crypto.fs_crypto_blkdev</code></td>
+ <td>Set by the <code>vold</code> command <code>checkpw</code> for later use by the <code>vold</code> command <code>restart</code>.</td>
+ </tr>
+ <tr>
+ <td><code>ro.crypto.state unencrypted</code></td>
+ <td>Set by <code>init</code> to say this system is running with an unencrypted
+ <code>/data ro.crypto.state encrypted</code>. Set by <code>init</code> to say this system is running with an encrypted <code>/data</code>.</td>
+ </tr>
+ <tr>
+ <td><p><code>ro.crypto.fs_type<br>
+ ro.crypto.fs_real_blkdev <br>
+ ro.crypto.fs_mnt_point<br>
+ ro.crypto.fs_options<br>
+ ro.crypto.fs_flags <br>
+ </code></p></td>
+ <td> These five properties are set by
+ <code>init</code> when it tries to mount <code>/data</code> with parameters passed in from
+ <code>init.rc</code>. <code>vold</code> uses these to setup the crypto mapping.</td>
+ </tr>
+ <tr>
+ <td><code>ro.crypto.tmpfs_options</code></td>
+ <td>Set by <code>init.rc</code> with the options init should use when mounting the tmpfs /data filesystem.</td>
+ </tr>
+</table>
+<h2 id=init_actions>Init actions</h2>
+
+<pre>
+on post-fs-data
+on nonencrypted
+on property:vold.decrypt=trigger_reset_main
+on property:vold.decrypt=trigger_post_fs_data
+on property:vold.decrypt=trigger_restart_min_framework
+on property:vold.decrypt=trigger_restart_framework
+on property:vold.decrypt=trigger_shutdown_framework
+on property:vold.decrypt=trigger_encryption
+on property:vold.decrypt=trigger_default_encryption
+</pre>
diff --git a/src/security/enhancements/enhancements41.jd b/src/security/enhancements/enhancements41.jd
new file mode 100644
index 0000000..2881c08
--- /dev/null
+++ b/src/security/enhancements/enhancements41.jd
@@ -0,0 +1,44 @@
+page.title=Security Enhancements in Android 1.5 through 4.1
+@jd:body
+
+<p>
+Android provides a multi-layered security model described in the <a href="{@docRoot}security/index.html">Android
+Security Overview</a>. Each update to Android includes dozens of
+security enhancements to protect users. The following are some of the security
+enhancements introduced in Android versions 1.5 through 4.1:</p>
+
+<dl>
+<dt><strong>Android 1.5</strong></dt>
+<dd><ul>
+<li>ProPolice to prevent stack buffer overruns (-fstack-protector)</li>
+<li>safe_iop to reduce integer overflows</li>
+<li>Extensions to OpenBSD dlmalloc to prevent double free() vulnerabilities and
+to prevent chunk consolidation attacks. Chunk consolidation attacks are a
+common way to exploit heap corruption.</li>
+<li>OpenBSD calloc to prevent integer overflows during memory allocation</li>
+</ul>
+</dd>
+
+<dt><strong>Android 2.3</strong></dt>
+<dd><ul>
+<li>Format string vulnerability protections (-Wformat-security -Werror=format-security)</li>
+<li>Hardware-based No eXecute (NX) to prevent code execution on the stack and heap</li>
+<li>Linux mmap_min_addr to mitigate null pointer dereference privilege
+escalation (further enhanced in Android 4.1)</li>
+</ul>
+</dd>
+
+<dt><strong>Android 4.0</strong></dt>
+<dd>Address Space Layout Randomization (ASLR) to randomize key locations in memory
+</dd>
+
+<dt><strong>Android 4.1</strong></dt>
+<dd><ul>
+<li>PIE (Position Independent Executable) support</li>
+<li>Read-only relocations / immediate binding (-Wl,-z,relro -Wl,-z,now)</li>
+<li>dmesg_restrict enabled (avoid leaking kernel addresses)</li>
+<li>kptr_restrict enabled (avoid leaking kernel addresses)</li>
+</ul>
+</dd>
+
+</dl>
diff --git a/src/security/enhancements/enhancements42.jd b/src/security/enhancements/enhancements42.jd
new file mode 100644
index 0000000..d6e48d5
--- /dev/null
+++ b/src/security/enhancements/enhancements42.jd
@@ -0,0 +1,60 @@
+page.title=Security Enhancements in Android 4.2
+@jd:body
+
+<p>
+Android provides a multi-layered security model described in the <a href="{@docRoot}security/index.html">Android
+Security Overview</a>. Each update to Android includes dozens of
+security enhancements to protect users. The following are some of the security
+enhancements introduced in Android 4.2:</p>
+
+<ul>
+<li><strong>Application verification</strong> - Users can choose to enable “Verify Apps" and
+have applications screened by an application verifier, prior to installation.
+App verification can alert the user if they try to install an app that might be
+harmful; if an application is especially bad, it can block installation.</li>
+<li><strong>More control of premium SMS</strong> - Android will provide a notification if an
+application attempts to send SMS to a short code that uses premium services
+which might cause additional charges. The user can choose whether to allow the
+application to send the message or block it.</li>
+
+<li><strong>Always-on VPN</strong> - VPN can be configured so that applications will not have
+access to the network until a VPN connection is established. This prevents
+applications from sending data across other networks.</li>
+
+<li><strong>Certificate Pinning</strong> - The Android core libraries now support
+<a href="https://developer.android.com/reference/android/net/http/X509TrustManagerExtensions.html">certificate pinning</a>.
+Pinned domains will receive a certificate validation
+failure if the certificate does not chain to a set of expected certificates.
+This protects against possible compromise of Certificate Authorities.</li>
+
+<li><strong>Improved display of Android permissions</strong> - Permissions have been organized
+into groups that are more easily understood by users. During review of the
+permissions, the user can click on the permission to see more detailed
+information about the permission.</li>
+
+<li><strong>installd hardening</strong> - The <code>installd</code> daemon does not run as the root user,
+reducing potential attack surface for root privilege escalation.</li>
+
+<li><strong>init script hardening</strong> - init scripts now apply <code>O_NOFOLLOW</code> semantics to
+prevent symlink related attacks.</li>
+
+<li><strong>FORTIFY_SOURCE</strong> - Android now implements <code>FORTIFY_SOURCE</code>. This is used by
+system libraries and applications to prevent memory corruption.</li>
+
+<li><strong>ContentProvider default configuration</strong> - Applications which target API
+level 17 will have "export" set to "false" by default for each
+<a href="https://developer.android.com/reference/android/content/ContentProvider.html">Content
+Provider</a>, reducing default attack surface for applications.</li>
+
+<li><strong>Cryptography</strong> - Modified the default implementations of SecureRandom and
+Cipher.RSA to use OpenSSL. Added SSL Socket support for TLSv1.1 and TLSv1.2
+using OpenSSL 1.0.1</li>
+
+<li><strong>Security Fixes</strong> - Upgraded open source libraries with security fixes include
+WebKit, libpng, OpenSSL, and LibXML. Android 4.2 also includes fixes for
+Android-specific vulnerabilities. Information about these vulnerabilities has
+been provided to Open Handset Alliance members and fixes are available in
+Android Open Source Project. To improve security, some devices with earlier
+versions of Android may also include these fixes.</li>
+
+</ul>
diff --git a/src/security/enhancements/enhancements43.jd b/src/security/enhancements/enhancements43.jd
new file mode 100644
index 0000000..277e010
--- /dev/null
+++ b/src/security/enhancements/enhancements43.jd
@@ -0,0 +1,87 @@
+page.title=Security Enhancements in Android 4.3
+@jd:body
+
+<p>
+Every Android release includes dozens of security enhancements to protect
+users. The following are some of the security enhancements available
+in Android 4.3:
+</p>
+
+<ul>
+ <li><strong>Android sandbox reinforced with SELinux.</strong>
+ This release strengthens the Android sandbox using the SELinux
+ mandatory access control system (MAC) in the Linux kernel. SELinux
+ reinforcement is invisible to users and developers, and adds robustness
+ to the existing Android security model while maintaining compatibility
+ with existing applications. To ensure continued compatibility this release
+ allows the use of SELinux in a permissive mode. This mode logs any policy
+ violations, but will not break applications or affect system behavior.</li>
+
+ <li><strong>No setuid/setgid programs.</strong>
+ Added support for filesystem capabilities
+ to Android system files and removed all setuid/setguid programs. This
+ reduces root attack surface and the likelihood of potential security
+ vulnerabilities.</li>
+
+ <li><strong>ADB Authentication.</strong>
+ Since Android 4.2.2, connections to ADB are
+ authenticated with an RSA keypair. This prevents unauthorized use of
+ ADB where the attacker has physical access to a device.</li>
+
+ <li><strong>Restrict Setuid from Android Apps.</strong>
+ The /system partition is now mounted
+ nosuid for zygote-spawned processes, preventing Android applications
+ from executing setuid programs. This reduces root attack surface and
+ the likelihood of potential security vulnerabilities.</li>
+
+ <li><strong>Capability bounding.</strong>
+ Android zygote and ADB now use prctl(PR_CAPBSET_DROP) to drop
+ unnecessary capabilities prior to executing applications.
+ This prevents Android applications and applications launched from
+ the shell from acquiring privileged capabilities.</li>
+
+ <li><strong>AndroidKeyStore Provider.</strong>
+ Android now has a keystore provider that allows
+ applications to create exclusive use keys. This provides applications
+ with an API to create or store private keys that cannot be used by
+ other applications.</li>
+
+ <li><strong>KeyChain isBoundKeyAlgorithm.</strong>
+ Keychain API now provides a method
+ (isBoundKeyType) that allows applications to confirm that system-wide keys
+ are bound to a hardware root of trust for the device. This provides
+ a place to create or store private keys that cannot be exported off the
+ device, even in the event of a root compromise.</li>
+
+ <li><strong>NO_NEW_PRIVS.</strong>
+ Android zygote now uses prctl(PR_SET_NO_NEW_PRIVS) to block addition
+ of new privileges prior to execution application code. This
+ prevents Android applications from performing operations which can
+ elevate privileges via execve. (This requires Linux kernel version 3.5
+ or greater).</li>
+
+ <li><strong>FORTIFY_SOURCE enhancements.</strong>
+ Enabled FORTIFY_SOURCE on Android x86 and MIPS
+ and fortified strchr(), strrchr(), strlen(), and umask() calls. This
+ can detect potential memory corruption vulnerabilities or unterminated
+ string constants.</li>
+
+ <li><strong>Relocation protections.</strong>
+ Enabled read only relocations (relro) for
+ statically linked executables and removed all text relocations in Android
+ code. This provides defense in depth against potential memory corruption
+ vulnerabilities.</li>
+
+ <li><strong>Improved EntropyMixer.</strong>
+ EntropyMixer now writes entropy at shutdown /
+ reboot, in addition to periodic mixing. This allows retention of all
+ entropy generated while devices are powered on, and is especially useful
+ for devices that are rebooted immediately after provisioning.</li>
+
+ <li><strong>Security Fixes.</strong>
+ Android 4.3 also includes fixes for Android-specific
+ vulnerabilities. Information about these vulnerabilities has been provided
+ to Open Handset Alliance members and fixes are available in Android Open
+ Source Project. To improve security, some devices with earlier versions
+ of Android may also include these fixes.</li>
+</ul>
diff --git a/src/security/enhancements/enhancements44.jd b/src/security/enhancements/enhancements44.jd
new file mode 100644
index 0000000..ec0aee8
--- /dev/null
+++ b/src/security/enhancements/enhancements44.jd
@@ -0,0 +1,48 @@
+page.title=Security Enhancements in Android 4.4
+@jd:body
+
+<p>
+Every Android release includes dozens of security enhancements to protect
+users. The following are some of the security enhancements available
+in Android 4.4:
+</p>
+
+<ul>
+ <li><strong>Android sandbox reinforced with SELinux.</strong>
+ Android now uses SELinux in enforcing mode. SELinux is a mandatory
+ access control (MAC) system in the Linux kernel used to augment the
+ existing discretionary access control (DAC) based security model.
+ This provides additional protection against potential security
+ vulnerabilities.</li>
+
+ <li><strong>Per User VPN.</strong>
+ On multi-user devices, VPNs are now applied per user.
+ This can allow a user to route all network traffic through a VPN
+ without affecting other users on the device.</li>
+
+ <li><strong>ECDSA Provider support in AndroidKeyStore.</strong>
+ Android now has a keystore provider that allows use of ECDSA and
+ DSA algorithms.</li>
+
+ <li><strong>Device Monitoring Warnings.</strong>
+ Android provides users with a warning if any certificate has been
+ added to the device certificate store that could allow monitoring of
+ encrypted network traffic.</li>
+
+ <li><strong>FORTIFY_SOURCE.</strong>
+ Android now supports FORTIFY_SOURCE level 2, and all code is compiled
+ with these protections. FORTIFY_SOURCE has been enhanced to work with
+ clang.</li>
+
+ <li><strong>Certificate Pinning.</strong>
+ Android 4.4 detects and prevents the use of fraudulent Google
+ certificates used in secure SSL/TLS communications.</li>
+
+ <li><strong>Security Fixes.</strong>
+ Android 4.4 also includes fixes for Android-specific vulnerabilities.
+ Information about these vulnerabilities has been provided to Open
+ Handset Alliance members and fixes are available in Android Open Source
+ Project. To improve security, some devices with earlier versions of
+ Android may also include these fixes.</li>
+
+</ul>
diff --git a/src/security/enhancements/enhancements50.jd b/src/security/enhancements/enhancements50.jd
new file mode 100644
index 0000000..7a143b6
--- /dev/null
+++ b/src/security/enhancements/enhancements50.jd
@@ -0,0 +1,56 @@
+page.title=Security Enhancements in Android 5.0
+@jd:body
+
+<p>Every Android release includes dozens of security enhancements to protect
+users. Here are some of the major security enhancements available in Android
+5.0:</p>
+
+<ul>
+ <li><strong>Encrypted by default.</strong> On devices that ship with L
+out-of-the-box, full disk encryption is enabled by default to improve
+protection of data on lost or stolen devices. Devices that
+update to L can be encrypted in <strong>Settings</strong> > <strong>Security</strong>.
+ <li><strong>Improved full disk encryption.</strong> The user password is
+protected against brute-force attacks using <code>scrypt</code> and, where
+available, the key is bound to the hardware keystore to prevent
+off-device attacks. As always, the Android screen lock secret and the device
+encryption key are not sent off the device or exposed to any application.
+ <li><strong>Android sandbox reinforced with SELinux</strong>. Android now
+requires SELinux in enforcing mode for all domains. SELinux is a
+mandatory access control (MAC) system in the Linux kernel used to augment the
+existing discretionary access control (DAC) security model. This new layer
+provides additional protection against potential security vulnerabilities.
+ <li><strong>Smart Lock. </strong>Android now includes trustlets that provide
+more flexibility for unlocking devices. For example, trustlets can allow
+devices to be unlocked automatically when close to another trusted device (via
+NFC, Bluetooth) or being used by someone with a trusted face.
+ <li><strong>Multi user, restricted profile, and guest modes for phones &
+tablets.</strong> Android now provides for multiple users on phones and
+includes a guest mode that can be used to provide easy temporary access to your
+device without granting access to your data and apps.
+ <li><strong>Updates to WebView without OTA. </strong> WebView can now be
+updated independent of the framework and without a system
+OTA. This will allow for faster response to potential security issues in
+WebView.
+ <li><strong>Updated cryptography for HTTPS and TLS/SSL.</strong> TLSv1.2 and
+TLSv1.1 is now enabled, Forward Secrecy is now preferred, AES-GCM
+is now enabled, and weak cipher suites (MD5, 3DES, and export cipher suites)
+are now disabled. See <a
+href="https://developer.android.com/reference/javax/net/ssl/SSLSocket.html">https://developer.android.com/reference/javax/net/ssl/SSLSocket.html</a>
+for more details.
+ <li><strong>non-PIE linker support removed.</strong> Android now requires all
+dynamically linked executables to support PIE
+(position-independent executables). This enhances Android’s address space
+layout randomization (ASLR) implementation.
+ <li><strong>FORTIFY_SOURCE improvements.</strong> The following libc
+functions now implement FORTIFY_SOURCE protections: <code>stpcpy()</code>,
+<code>stpncpy()</code>, <code>read()</code>, <code>recvfrom()</code>,
+<code>FD_CLR()</code>, <code>FD_SET()</code>, and <code>FD_ISSET()</code>. This
+provides protection against memory-corruption vulnerabilities involving
+those functions.
+ <li><strong>Security Fixes.</strong> Android 5.0 also includes fixes for
+Android-specific vulnerabilities. Information about these vulnerabilities has
+been provided to Open Handset Alliance members, and fixes are available in
+Android Open Source Project. To improve security, some devices with earlier
+versions of Android may also include these fixes.
+</ul>
diff --git a/src/security/enhancements/enhancements60.jd b/src/security/enhancements/enhancements60.jd
new file mode 100644
index 0000000..7cc786e
--- /dev/null
+++ b/src/security/enhancements/enhancements60.jd
@@ -0,0 +1,38 @@
+page.title=Security Enhancements in Android 6.0
+@jd:body
+
+<p>Every Android release includes dozens of security enhancements to protect
+users. Here are some of the major security enhancements available in Android
+6.0:</p>
+<ul>
+ <li><strong>Runtime Permissions</strong>. Applications request permissions at
+ runtime instead of being granted at App
+ install time. Users can toggle permissions on and off for both M and pre-M
+ applications.</li>
+ <li><strong>Verified Boot</strong>. A set of cryptographic checks of system
+ software are conducted prior to
+ execution to ensure the phone is healthy from the bootloader all the way up to
+ the operating system.</li>
+ <li><strong>Hardware-Isolated Security</strong>. New Hardware Abstraction
+ Layer (HAL) used by Fingerprint API, Lockscreen,
+ Device Encryption, and Client Certificates to protect keys against kernel
+ compromise and/or local physical attacks</li>
+ <li><strong>Fingerprints</strong>. Devices can now be unlocked with just a
+ touch. Developers can also take
+ advantage of new APIs to use fingerprints to lock and unlock encryption keys.</li>
+ <li><strong>SD Card Adoption</strong>. Removable media can be
+ <em>adopted</em> to a device and expand available storage for
+ app local data, photos, videos, etc., but still be protected by block-level
+ encryption.</li>
+ <li><strong>Clear Text Traffic</strong>. Developers can use a new StrictMode
+ to make sure their application doesn't use
+ cleartext.</li>
+ <li><strong>System Hardening</strong>. Hardening of the system via policies
+ enforced by SELinux. This offers better
+ isolation between users, IOCTL filtering, reduce threat of exposed services,
+ further tightening of SELinux domains, and extremely limited /proc access.</li>
+ <li><strong>USB Access Control:</strong> Users must confirm to allow USB
+ access to files, storage, or other
+ functionality on the phone. Default is now <em>charge only</em> with access
+ to storage requiring explicit approval from the user.</li>
+</ul>
diff --git a/src/security/enhancements/index.jd b/src/security/enhancements/index.jd
new file mode 100644
index 0000000..82ef403
--- /dev/null
+++ b/src/security/enhancements/index.jd
@@ -0,0 +1,20 @@
+page.title=Security Enhancements
+@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.
+-->
+<p>Android continuously improves its security abilities and offerings. See the
+lists of enhancements by release in the left navigation.</p>
diff --git a/src/security/images/access-to-keymaster.png b/src/security/images/access-to-keymaster.png
new file mode 100644
index 0000000..611f8e3
--- /dev/null
+++ b/src/security/images/access-to-keymaster.png
Binary files differ
diff --git a/src/security/images/android_software_stack.png b/src/security/images/android_software_stack.png
new file mode 100644
index 0000000..170ea33
--- /dev/null
+++ b/src/security/images/android_software_stack.png
Binary files differ
diff --git a/src/security/images/authentication-flow.png b/src/security/images/authentication-flow.png
new file mode 100644
index 0000000..1c136e4
--- /dev/null
+++ b/src/security/images/authentication-flow.png
Binary files differ
diff --git a/src/security/images/boot_orange.png b/src/security/images/boot_orange.png
new file mode 100644
index 0000000..1a239d3
--- /dev/null
+++ b/src/security/images/boot_orange.png
Binary files differ
diff --git a/src/security/images/boot_red.png b/src/security/images/boot_red.png
new file mode 100644
index 0000000..44deda3
--- /dev/null
+++ b/src/security/images/boot_red.png
Binary files differ
diff --git a/src/security/images/boot_yellow1.png b/src/security/images/boot_yellow1.png
new file mode 100644
index 0000000..b68572d
--- /dev/null
+++ b/src/security/images/boot_yellow1.png
Binary files differ
diff --git a/src/security/images/boot_yellow2.png b/src/security/images/boot_yellow2.png
new file mode 100644
index 0000000..57732f5
--- /dev/null
+++ b/src/security/images/boot_yellow2.png
Binary files differ
diff --git a/src/security/images/dm-verity-hash-table.png b/src/security/images/dm-verity-hash-table.png
new file mode 100644
index 0000000..d094531
--- /dev/null
+++ b/src/security/images/dm-verity-hash-table.png
Binary files differ
diff --git a/src/security/images/dm-verity_mgmt.png b/src/security/images/dm-verity_mgmt.png
new file mode 100644
index 0000000..2c2854e
--- /dev/null
+++ b/src/security/images/dm-verity_mgmt.png
Binary files differ
diff --git a/src/security/images/fingerprint-daemon.png b/src/security/images/fingerprint-daemon.png
new file mode 100644
index 0000000..a57a7a4
--- /dev/null
+++ b/src/security/images/fingerprint-daemon.png
Binary files differ
diff --git a/src/security/images/fingerprint-data-flow.png b/src/security/images/fingerprint-data-flow.png
new file mode 100644
index 0000000..bc3ff36
--- /dev/null
+++ b/src/security/images/fingerprint-data-flow.png
Binary files differ
diff --git a/src/security/images/gatekeeper-flow.png b/src/security/images/gatekeeper-flow.png
new file mode 100644
index 0000000..693ebec
--- /dev/null
+++ b/src/security/images/gatekeeper-flow.png
Binary files differ
diff --git a/src/security/images/image00.png b/src/security/images/image00.png
new file mode 100644
index 0000000..789dc4e
--- /dev/null
+++ b/src/security/images/image00.png
Binary files differ
diff --git a/src/security/images/image02.png b/src/security/images/image02.png
new file mode 100644
index 0000000..1696a97
--- /dev/null
+++ b/src/security/images/image02.png
Binary files differ
diff --git a/src/security/images/image03.png b/src/security/images/image03.png
new file mode 100644
index 0000000..a231fb3
--- /dev/null
+++ b/src/security/images/image03.png
Binary files differ
diff --git a/src/security/images/image_gmail_installed.png b/src/security/images/image_gmail_installed.png
new file mode 100644
index 0000000..aef5aeb
--- /dev/null
+++ b/src/security/images/image_gmail_installed.png
Binary files differ
diff --git a/src/security/images/image_install.png b/src/security/images/image_install.png
new file mode 100644
index 0000000..87f7516
--- /dev/null
+++ b/src/security/images/image_install.png
Binary files differ
diff --git a/src/security/images/patchreward.png b/src/security/images/patchreward.png
new file mode 100644
index 0000000..496fe64
--- /dev/null
+++ b/src/security/images/patchreward.png
Binary files differ
diff --git a/src/security/images/permissions_check.png b/src/security/images/permissions_check.png
new file mode 100644
index 0000000..0dc2e02
--- /dev/null
+++ b/src/security/images/permissions_check.png
Binary files differ
diff --git a/src/security/images/tiny-robot.png b/src/security/images/tiny-robot.png
new file mode 100644
index 0000000..2cb88ca
--- /dev/null
+++ b/src/security/images/tiny-robot.png
Binary files differ
diff --git a/src/security/images/verified_boot.png b/src/security/images/verified_boot.png
new file mode 100644
index 0000000..b1c5cb6
--- /dev/null
+++ b/src/security/images/verified_boot.png
Binary files differ
diff --git a/src/security/implement.jd b/src/security/implement.jd
new file mode 100644
index 0000000..2a7c890
--- /dev/null
+++ b/src/security/implement.jd
@@ -0,0 +1,392 @@
+page.title=Implementing Security
+@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>The Android Security Team regularly receive requests for more information about
+how to prevent potential security issues on Android devices. We also
+occasionally perform spot-checks of devices and let OEMs and affected partners
+know of potential issues.</p>
+
+<p>This document provides OEMs and other partners with a number of security best
+practices based upon our own experiences. This is an extension of the
+<a href="http://developer.android.com/guide/practices/security.html">Designing for
+Security</a> documentation we've provided for developers, including best
+practices that are unique to those who are building or installing system-level
+software on devices.</p>
+
+<p>Where possible, the Android Security Team will incorporate tests into the
+<a href="{@docRoot}compatibility/cts-intro.html">Android Compatibility Test
+Suite</a> (CTS) and
+<a href="http://tools.android.com/tips/lint">Android Lint</a> to facilitate adoption of
+these best practices. We encourage partners to contribute tests that can help
+other Android users. A partial list of security-related tests can be found at:
+<code>root/cts/tests/tests/security/src/android/security/cts</code></p>
+
+<h2 id="dev-process">Development process</h2>
+
+<h3 id="sec-review">Source code security review</h3>
+<p> Source code review can detect a broad range of security issues, including those
+identified in this document. Android strongly encourages both manual and
+automated source code review.</p>
+
+<ol>
+<li><a href="http://tools.android.com/tips/lint">Android Lint</a>
+<strong>should</strong> be run on all application code using the Android SDK.
+Issues that are identified should be corrected.</li>
+<li>Native code <strong>should</strong> be analyzed using an automated tool that
+can detect memory management issues such as buffer overflows and off-by-one
+errors.</li>
+</ol>
+
+<h3 id="auto-test">Automated testing</h3>
+<p>Automated testing can detect a broad range of security issues, including many of
+those identified in this document.</p>
+
+<ol>
+<li>CTS is regularly updated with security tests; the most recent version of CTS
+<strong>must</strong> be run to verify compatibility.</li>
+<li>CTS <strong>should</strong> be run regularly throughout the development process to detect
+problems early and reduce time to correction. Android uses CTS as part of
+continuous integration with our automated build process, which builds
+multiple times per day.</li>
+<li>OEMs <strong>should</strong> automate security testing of any interfaces including testing
+with malformed inputs (fuzz testing).</li>
+</ol>
+
+<h3 id="sign-sysimg">Signing system images</h3>
+<p>The signature of the system image is critical for determining the integrity of
+the device. Specifically:</p>
+
+<ol>
+<li>Devices <strong>must not</strong> be signed with a key that is publicly known.</li>
+<li>Keys used to sign devices <strong>should</strong> be managed in a manner consistent with
+industry standard practices for handling sensitive keys, including a hardware
+security module (HSM) that provides limited, auditable access.</li>
+</ol>
+
+<h3 id="sign-apk">Signing applications (APKs)</h3>
+<p>Application signatures play an important role in device security. They are used
+for permissions checks as well as software updates. When selecting a key to use
+for signing applications, it is important to consider whether an application
+will be available only on a single device or common across multiple devices.
+Consider:</p>
+
+<ol>
+<li>Applications <strong>must not</strong> be signed with a key that is publicly known.</li>
+<li>Keys used to sign applications <strong>should</strong> be managed in a manner consistent
+with industry standard practices for handling sensitive keys, including an
+HSM that provides limited, auditable access.</li>
+<li>Applications <strong>should not</strong> be signed with the platform key.</li>
+<li>Applications with the same package name <strong>should not</strong> be signed with
+different keys. This often occurs when creating an application for different
+devices, especially when using the platform key. If the application is
+device-independent, then use the same key across devices. If the application
+is device-specific, create unique package names per device and key.</li>
+</ol>
+
+<h3 id="apps-pub">Apps publishing</h3>
+<p>Google Play provides OEMs with the ability to update applications without
+performing a complete system update. This can expedite response to security
+issues and delivery of new features. This also provides a way to make sure that
+your application has a unique package name.</p>
+
+<ol>
+<li>Apps <strong>should</strong> be uploaded to Google Play to allow automated updates without
+requiring a full OTA. Applications that are uploaded but "unpublished" are
+not directly downloadable by users, but the apps are still updated. Users who
+have ever installed such an app can install it again and again on their other
+devices as well.</li>
+<li>To avoid potential confusion, apps <strong>should</strong> be created with a package name
+clearly associated with your company, such as by using a company trademark.</li>
+<li>Apps published by OEMs <strong>should</strong> be uploaded on the Google Play store in
+order to avoid package name impersonation by third-party users.<br/>
+<br/>
+If an OEM installs an app on a phone without publishing it on the Play store,
+another developer could upload that same app, using the same package name,,
+and change the metadata for the app. When presented to the user, this
+unrelated metadata could create confusion.</li>
+</ol>
+
+<h3 id="incident-response">Incident response</h3>
+<p>External parties must have the ability to contact OEMs about device-specific
+security issues. We strongly recommend the creation of a publicly accessible
+email address for managing security incidents.</p>
+
+<ol>
+<li>Create a <em>security@your-company.com</em> or similar address and publicize
+it.</li>
+<li>If you become aware of a security issue affecting Android OS or Android
+devices from multiple OEMs, you <strong>should</strong> contact the Android
+Security Team at <em>security@android.com</em>.</li>
+</ol>
+
+<h2 id="prod-implement">Product implementation</h2>
+
+<h3 id="root-processes">Root processes</h3>
+<p>Root processes are the most frequent target of privilege escalation attacks, so
+reducing the number of root processes reduces risk of privilege escalation. CTS
+has been expanded with an informational test that lists root processes.</p>
+
+<ol>
+<li>The devices <strong>should</strong> run the minimum necessary code as root. Where
+possible, use a regular android process rather than a root process. The ICS
+Galaxy Nexus has only six root processes - vold, inetd, zygote, tf_daemon,
+ueventd, and init. Please let the Android team know if capabilities are
+required that are not accessible without root privileges.</li>
+<li>Where possible, root code <strong>should</strong> be isolated from untrusted data and
+accessed via IPC. For example, reduce root functionality to a small Service
+accessible via Binder and expose the Service with signature permission to an
+application with low or no privileges to handle network traffic.</li>
+<li>Root processes <strong>must not</strong> listen on a network socket.</li>
+<li>Root processes <strong>must not</strong> provide a general-purpose runtime for
+applications. (e.g. a Java VM)</li>
+</ol>
+
+<h3 id="sys-apps">System apps</h3>
+<p>In general, apps pre-installed by OEMs should not be running with the shared UID
+of system. Realistically, however, sometimes this is necessary. If an app is
+using the shared UID of system or another privileged service (i.e., phone), it
+should not export any services, broadcast receivers, or content providers that
+can be accessed by third-party apps installed by users.</p>
+
+<ol>
+<li>The devices <strong>should</strong> run the minimum necessary code as system. Where
+possible, use an android process with its own UID rather than reusing the
+system UID.</li>
+<li>Where possible, system code <strong>should</strong> be isolated from untrusted data and
+expose IPC only to other trusted processes.</li>
+<li>System processes <strong>must not</strong> listen on a network socket.</li>
+</ol>
+
+<h3 id="process-isolate">Process isolation</h3>
+<p>The Android Application Sandbox provides applications with an expectation of
+isolation from other processes on the system, including root processes and
+debuggers. Unless debugging is specifically enabled by the application and the
+user, no application should violate that expectation.</p>
+
+<ol>
+<li>Root processes <strong>must not</strong> access data within individual application data
+folders, unless using a documented Android debugging method.</li>
+<li>Root processes <strong>must not</strong> access memory of applications, unless using a
+documented Android debugging method.</li>
+<li>The device <strong>must not</strong> include any application that accesses data or memory
+of other applications or processes.</li>
+</ol>
+
+<h3 id="suid-files">SUID files</h3>
+<p>New setuid programs should not be accessible by untrusted programs. Setuid
+programs have frequently been the location of vulnerabilities that can be used
+to gain root access, and minimizing the availability of the program to untrusted
+applications is a security best practice.</p>
+
+<ol>
+<li>SUID processes <strong>must not</strong> provide a shell or backdoor that can be used to
+circumvent the Android security model.</li>
+<li>SUID programs <strong>must not</strong> be writable by any user.</li>
+<li>SUID programs <strong>should</strong> not be world readable or executable. Create a
+group, limit access to the SUID binary to members of that group, and place any
+applications that should be able to execute the SUID program into that
+group.</li>
+<li>SUID programs are a common source of user "rooting" of devices. To reduce
+this risk, SUID programs <strong>should not</strong> be executable by the shell
+user.</li>
+</ol>
+
+<p>The CTS verifier has been expanded with an informational test that lists SUID
+files. Certain setuid files are not permitted, per CTS tests.</p>
+
+<h3 id="listening-sockets">Listening sockets</h3>
+<p>CTS tests have been expanded to fail when a device is listening on any port, on
+any interface. In the event of a failure, Google will verify that the following
+best practices are being used:</p>
+
+<ol>
+<li>There <strong>should</strong> be no listening ports on the device.</li>
+<li>Listening ports <strong>must</strong> be able to be disabled without an OTA.
+This can be either a server or user-device configuration change.</li>
+<li>Root processes <strong>must not</strong> listen on any port.</li>
+<li>Processes owned by the system UID <strong>must not</strong> listen on any
+port.</li>
+<li>For local IPC using sockets, applications <strong>must</strong> use a UNIX
+Domain Socket with access limited to a group. Create a file descriptor for the
+IPC and make it +RW for a specific UNIX group. Any client applications must be
+within that UNIX group.</li>
+<li>Some devices with multiple processors (e.g. a radio/modem separate from the
+application processor) use network sockets to communicate between processors.
+In those instances, the network socket used for inter-processor communication
+<strong>must</strong> use an isolated network interface to prevent access by
+unauthorized
+applications on the device. One approach is to use iptables to prevent access by
+other applications on the device.</li>
+<li>Daemons that handle listening ports <strong>must</strong> be robust against malformed
+data. Google may conduct fuzz-testing against the port using an unauthorized
+client, and, where possible, authorized client. Any crashes will be filed as
+bugs with an appropriate severity.</li>
+</ol>
+
+<h3 id="logging">Logging</h3>
+<p>Logging of data increases the risk of exposure of that data and reduces system
+performance. Multiple public security incidents have occurred as the result of
+logging of sensitive user data by applications installed by default on Android
+devices.</p>
+
+<ol>
+<li>Applications or system services <strong>should not</strong> log data provided from
+third-party applications that might include sensitive information.</li>
+<li>Applications <strong>must not</strong> log any Personally Identifiable Information (PII)
+as part of normal operation.</li>
+</ol>
+
+<p>CTS has been expanded with a number of tests that check for the presence of
+potentially sensitive information in the system logs.</p>
+
+<h3 id="directories">Directories</h3>
+<p>World-writable directories can introduce security weaknesses. Writable
+directories may enable an application to rename other trusted files,
+substituting their own files or conducting symlink-based attacks. By creating a
+symlink to a file, the attacker may trick a trusted program into performing
+actions it shouldn't.</p>
+
+<p> Writable directories prevent the uninstall of an application from properly
+cleaning up all files associated with an application. Directories created by the
+system or root users <strong>should not</strong> be world writable.</p>
+
+<p>CTS tests help enforce this best practice by testing known directories.</p>
+
+<h3 id="config-files">Configuration files</h3>
+<p>Many drivers and services rely on configuration and data files stored in
+directories like /system/etc and various other directories in /data. If these
+files are processed by a privileged process and are world writable, then it
+could be possible for an app to exploit a vulnerability in the process by
+crafting malicious contents in the world-writable file.</p>
+
+<ol>
+<li>Configuration files used by privileged processes <strong>should not</strong>
+be world readable.</li>
+<li>Configuration files used by privileged processes <strong>must not</strong> be
+world writable.</li>
+</ol>
+
+<h3 id="native-code">Native code libraries</h3>
+<p>Any code used by privileged OEM processes must be in /vendor or /system; these
+filesystems are mounted read-only on boot. Any libraries used by system or other
+highly-privileged apps installed on the phone should also be in these
+filesystems. This can prevent a security vulnerability that could allow an
+attacker to control the code that a privileged process executes.</p>
+
+<ol>
+<li>All native code used by privileged OEM processes <strong>must be</strong> in /vendor or
+/system.</li>
+</ol>
+
+<h3 id="device-drivers">Device drivers</h3>
+<p>Only trusted code should have direct access to drivers. Where possible, the
+preferred architecture is to provide a single-purpose daemon that proxies calls
+to the driver and restrict access to the driver to that daemon.</p>
+
+<p>Driver device nodes <strong>should not</strong> be world readable or
+writable. CTS tests help enforce this best practice by checking for known
+instances of exposed drivers.</p>
+
+<h3 id="adb">ADB</h3>
+<p>ADB <strong>must be</strong> disabled by default and must require the user to turn it on
+before accepting connections.</p>
+
+<h3 id="unlockable-bootloaders">Unlockable bootloaders</h3>
+<p>Unlockable Android devices must securely erase all user data prior to being
+unlocked. The failure to properly delete all data on unlocking may allow a
+physically proximate attacker to gain unauthorized access to confidential
+Android user data. We've seen numerous instances where device manufacturers
+improperly implemented unlocking.</p>
+
+<p>Many Android devices support unlocking. This allows the device owner to modify
+the system partition and/or install a custom operating system. Common use cases
+for this include installing a third-party ROM, and/or doing systems-level
+development on the device.</p>
+
+<p>For example, on Google Nexus devices, an end user can run <code>fastboot oem
+unlock</code> to start the unlocking process. When an end user runs this command,
+the following message is displayed:</p>
+
+<blockquote>
+<strong>Unlock bootloader?</strong>
+
+<p>If you unlock the bootloader, you will be able to install custom operating
+system software on this phone.</p>
+
+<p>A custom OS is not subject to the same testing as the original OS, and can
+cause your phone and installed applications to stop working properly.</p>
+
+<p>To prevent unauthorized access to your personal data, unlocking the
+bootloader will also delete all personal data from your phone (a "factory data
+reset").
+
+<p>Press the Volume Up/Down buttons to select Yes or No. Then press the Power
+button to continue.</p>
+
+<p><strong>Yes</strong>: Unlock bootloader (may void warranty)</p>
+
+<p><strong>No</strong>: Do not unlock bootloader and restart phone.</p>
+</blockquote>
+
+<p>A device that is unlocked may be subsequently relocked, by issuing the
+<code>fastboot oem lock</code> command. Locking the bootloader provides the same
+protection of user data with the new custom OS as was available with the
+original OEM OS. e.g. user data will be wiped if the device is unlocked again in
+the future.</p>
+
+<p>To prevent the disclosure of user data, a device that supports unlocking needs
+to implement it properly.</p>
+
+<p>A properly implemented unlocking process will have the following properties:</p>
+
+<ol>
+<li>When the unlocking command is confirmed by the user, the device MUST start an
+immediate data wipe. The "unlocked" flag MUST NOT be set until after the
+secure deletion is complete.</li>
+<li>If a secure deletion cannot be completed, the device MUST stay in a locked
+state.</li>
+<li>If supported by the underlying block device,
+<code>ioctl(BLKSECDISCARD)</code> or equivalent SHOULD be used. For eMMC
+devices, this means using a Secure Erase or Secure Trim command. For eMMC 4.5
+and later, this means doing a normal Erase or Trim followed by a Sanitize
+operation.</li>
+<li>If <code>BLKSECDISCARD</code> is NOT supported by the underlying block
+device, <code>ioctl(BLKDISCARD)</code> MUST be used instead. On eMMC devices,
+this is a normal Trim operation.</li>
+<li>If <code>BLKDISCARD</code> is NOT supported, overwriting the block devices
+with all zeros is acceptable.</li>
+<li>An end user MUST have the option to require that user data be wiped prior to
+flashing a partition. For example, on Nexus devices, this is done via the
+<code>fastboot oem lock</code> command.</li>
+<li>A device MAY record, via efuses or similar mechanism, whether a device was
+unlocked and/or relocked.</li>
+</ol>
+
+<p>These requirements ensure that all data is destroyed upon the completion of an
+unlock operation. Failure to implement these protections is considered a
+"moderate" level security vulnerability.</p>
diff --git a/src/security/index.jd b/src/security/index.jd
new file mode 100644
index 0000000..fb3db45
--- /dev/null
+++ b/src/security/index.jd
@@ -0,0 +1,140 @@
+page.title=Security
+@jd:body
+<!--
+ Copyright 2015 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 is a modern mobile platform that was designed to be truly open. Android
+ applications make use of advanced hardware and software, as well as local and
+ served data, exposed through the platform to bring innovation and value to
+ consumers. To protect that value, the platform must offer an application
+ environment that ensures the security of users, data, applications, the device,
+ and the network.</p>
+<p>Securing an open platform requires a robust security architecture and
+ rigorous security programs. Android was designed with multi-layered
+ security that provides the flexibility required for an open platform, while
+ providing protection for all users of the platform. For information about
+ reporting security issues and the update process,
+ see <a href="overview/updates-resources.html">Security Updates and Resources</a>.</p>
+<p>Android was designed with developers in mind. Security controls were designed
+ to reduce the burden on developers. Security-savvy developers can easily work
+ with and rely on flexible security controls. Developers less familiar with
+ security will be protected by safe defaults.</p>
+<p>Android was designed with device users in mind. Users are provided visibility
+ into how applications work, and control over those applications. This design
+ includes the expectation that attackers would attempt to perform common
+ attacks, such as social engineering attacks to convince device users to install
+ malware, and attacks on third-party applications on Android. Android was
+ designed to both reduce the probability of these attacks and greatly limit the
+ impact of the attack in the event it was successful.</p>
+<p>This documentation outlines the goals of the Android security program, describes the
+ fundamentals of the Android security architecture, and answers the most
+ pertinent questions for system architects and security analysts. This document
+ focuses on the security features of Android's core platform and does not
+ discuss security issues that are unique to specific applications, such as those
+ related to the browser or SMS application. Recommended best practices for
+ building Android devices, deploying Android devices, or developing applications
+ for Android are not the goal of this document and are provided elsewhere.</p>
+
+<h2 id="background">Background</h2>
+<p>Android provides an open source platform and application environment for mobile
+ devices.</p>
+<p>The sections and pages below describe the security features of the Android
+ platform. <em>Figure 1</em> summarizes the security components and considerations of
+ the various levels of the Android software stack. Each component assumes that
+ the components below are properly secured. With the exception of a small amount
+ of Android OS code running as root, all code above the Linux Kernel is
+ restricted by the Application Sandbox.</p>
+<p><img alt="Figure 1: Android software stack" src="images/android_software_stack.png" /></p>
+<p><em>Figure 1: Android software stack.</em></p>
+<p>The main Android platform building blocks are:</p>
+<ul>
+ <li>
+ <p><strong>Device Hardware</strong>: Android runs on a wide range of hardware configurations
+ including smart phones, tablets, and set-top-boxes. Android is
+ processor-agnostic, but it does take advantage of some hardware-specific
+ security capabilities such as ARM v6 eXecute-Never.</p>
+ </li>
+ <li>
+ <p><strong>Android Operating System</strong>: The core operating system is built on top of
+ the Linux kernel. All device resources, like camera functions, GPS data,
+ Bluetooth functions, telephony functions, network connections, etc. are
+ accessed through the operating system.</p>
+ </li>
+ <li>
+ <p><strong>Android Application Runtime</strong>: Android applications are most often written
+ in the Java programming language and run in the Dalvik virtual machine.
+ However, many applications, including core Android services and applications
+ are native applications or include native libraries. Both Dalvik and native
+ applications run within the same security environment, contained within the
+ Application Sandbox. Applications get a dedicated part of the filesystem in
+ which they can write private data, including databases and raw files.</p>
+ </li>
+</ul>
+<p>Android applications extend the core Android operating system. There are two
+ primary sources for applications:</p>
+<ul>
+ <li>
+ <p><strong>Pre-Installed Applications</strong>: Android includes a set of pre-installed
+ applications including phone, email, calendar, web browser, and contacts. These
+ function both as user applications and to provide key device capabilities that
+ can be accessed by other applications. Pre-installed applications may be part
+ of the open source Android platform, or they may be developed by an OEM for a
+ specific device.</p>
+ </li>
+ <li>
+ <p><strong>User-Installed Applications</strong>: Android provides an open development
+ environment supporting any third-party application. Google Play offers
+ users hundreds of thousands of applications.</p>
+ </li>
+</ul>
+<p>Google provides a set of cloud-based services that are available to any
+ compatible Android device. The primary services are:</p>
+<ul>
+ <li>
+ <p><strong>Google Play</strong>: Google Play is a collection of services that
+ allow users to discover, install, and purchase applications from their Android
+ device or the web. Google Play makes it easy for developers to reach Android
+ users and potential customers. Google Play also provides community review,
+ application <a href="https://developer.android.com/guide/publishing/licensing.html">license
+ verification</a>, application security scanning, and other security services.</p>
+ </li>
+ <li>
+ <p><strong>Android Updates</strong>: The Android update service delivers new capabilities and
+ security updates to Android devices, including updates through the web or over
+ the air (OTA).</p>
+ </li>
+ <li>
+ <p><strong>Application Services</strong>: Frameworks that allow Android applications to use
+ cloud capabilities such as (<a href="https://developer.android.com/guide/topics/data/backup.html">backing
+ up</a>) application
+ data and settings and cloud-to-device messaging
+ (<a href="https://developers.google.com/android/c2dm/">C2DM</a>)
+ for push messaging.</p>
+ </li>
+</ul>
+<p>These services are not part of the Android Open Source Project and are out
+ of scope for this document. But they are relevant to the security of most
+ Android devices, so a related security document titled “Google Services for
+ Android: Security Overview” is available.</p>
+
+
diff --git a/src/security/overview/acknowledgements.jd b/src/security/overview/acknowledgements.jd
new file mode 100644
index 0000000..13b4f68
--- /dev/null
+++ b/src/security/overview/acknowledgements.jd
@@ -0,0 +1,338 @@
+page.title=Android Security Acknowledgements
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>The Android Security Team would like to thank the following people and
+parties for helping to improve Android security. They have done this either by
+finding and responsibly reporting security vulnerabilities to <a
+href="mailto:security@android.com">security@android.com</a> or by committing code
+that has a positive impact on Android security, including code that qualifies
+for the <a href="https://www.google.com/about/appsecurity/patch-rewards/">Patch
+Rewards</a> program.</p>
+
+<h2 id=2015>2015</h2>
+
+<div style="LINE-HEIGHT:25px;">
+
+<p>
+<a href="mailto:jgor@utexas.edu">jgor</a> of <a href="http://security.utexas.edu">The University of Texas at Austin</a> (<a href="https://twitter.com/indiecom">@indiecom</a>)
+</p>
+
+<p><a href="mailto:higongguang@gmail.com">Guang Gong</a> of <a href="http://www.360safe.com/">Qihoo 360 Technology Co. Ltd</a> (<a href="https://twitter.com/oldfresher">@oldfresher</a>)</p>
+
+<p>Stephan Huber of Testlab Mobile Security, <a
+href="https://www.sit.fraunhofer.de/">Fraunhofer SIT</a> (<a
+href="mailto:Stephan.Huber@sit.fraunhofer.de">Stephan.Huber@sit.fraunhofer.de</a>)
+</p>
+
+<p><a
+href="http://www.ec-spride.tu-darmstadt.de/en/research-groups/secure-software-engineering-group/staff/siegfried-rasthofer/">Siegfried
+Rasthofer</a> of <a href="http://sseblog.ec-spride.de/">Secure Software
+Engineering Group</a>, EC SPRIDE Technische Universität Darmstadt (<a
+href="mailto:siegfried.rasthofer@gmail.com">siegfried.rasthofer@gmail.com</a>)</p>
+
+<p><a href="mailto:laginimaineb@gmail.com">Gal Beniamini</a> (<a href="http://bits-please.blogspot.com">http://bits-please.blogspot.com</a>)</p>
+
+<p>Michael Peck of <a href="https://www.mitre.org">The MITRE Corporation</a>
+(<a href="mailto:mpeck@mitre.org">mpeck@mitre.org</a>)</p>
+
+</div>
+
+<h2 id=2014>2014</h2>
+
+<div style="LINE-HEIGHT:25px;">
+<p>Jeff Forristal of <a href="http://www.bluebox.com/blog/">Bluebox
+Security</a></p>
+
+<p>Aaron Mangel of <a href="https://banno.com/">Banno</a> (<a
+href="mailto:amangel@gmail.com">amangel@gmail.com</a>)</p>
+
+<p><a href="http://www.linkedin.com/in/tonytrummer/">Tony Trummer</a> of <a
+href="http://www.themeninthemiddle.com">The Men in the Middle</a> <br>(<a
+href="https://twitter.com/SecBro1">@SecBro1</a>)</p>
+
+<p><a href="http://www.samsung.com">Samsung Mobile</a></p>
+
+<p>Henry Hoggard of <a href="https://labs.mwrinfosecurity.com/">MWR Labs</a> (<a
+href="https://twitter.com/henryhoggard">@HenryHoggard</a>)</p>
+
+<p><a href="http://www.androbugs.com">Yu-Cheng Lin 林禹成</a> (<a
+href="https://twitter.com/AndroBugs">@AndroBugs</a>)</p>
+
+<p><a
+href="http://www.ec-spride.tu-darmstadt.de/en/research-groups/secure-software-engineering-group/staff/siegfried-rasthofer/">Siegfried
+Rasthofer</a> of <a href="http://sseblog.ec-spride.de/">Secure Software
+Engineering Group</a>, EC SPRIDE Technische Universität Darmstadt (<a
+href="mailto:siegfried.rasthofer@gmail.com">siegfried.rasthofer@gmail.com</a>)</p>
+
+<p>Steven Arzt of <a href="http://sseblog.ec-spride.de/">Secure Software
+Engineering Group</a>, EC SPRIDE Technische Universität Darmstadt (<a
+href="mailto:Steven.Arzt@ec-spride.de">Steven.Arzt@ec-spride.de</a>)</p>
+
+<p><a href="http://blog.redfern.me/">Joseph Redfern</a> of <a
+href="https://labs.mwrinfosecurity.com/">MWR Labs</a> <br>(<a
+href="https://twitter.com/JosephRedfern">@JosephRedfern</a>)</p>
+
+<p><a href="https://plus.google.com/u/0/109528607786970714118">Valera
+Neronov</a></p>
+
+<p><a href="https://github.com/michalbednarski">Michał Bednarski</a></p>
+
+<p><a href="http://www.linkedin.com/in/luander">Luander Michel Ribeiro</a> (<a
+href="https://twitter.com/luanderock">@luanderock</a>)</p>
+
+<p>Stephan Huber of Testlab Mobile Security, <a
+href="https://www.sit.fraunhofer.de/">Fraunhofer SIT</a> (<a
+href="mailto:Stephan.Huber@sit.fraunhofer.de">Stephan.Huber@sit.fraunhofer.de</a>)
+</p>
+
+<p><a href="http://www.corkami.com">Ange Albertini</a> (<a
+href="https://twitter.com/angealbertini">@angealbertini</a>)</p>
+
+<p><a href="https://www.linkedin.com/in/tdalvi">Tushar Dalvi</a> (<a
+href="https://twitter.com/tushardalvi">@tushardalvi</a>)</p>
+
+<p>Axelle Apvrille of Fortinet, FortiGuards Labs</p>
+
+<p>Tongxin Li of Peking University (<a
+href="mailto:litongxin1991@gmail.com">litongxin1991@gmail.com</a>)</p>
+
+<p><a href="https://www.facebook.com/zhou.xiaoyong">Xiaoyong Zhou</a> of <a
+href="http://www.cs.indiana.edu/~zhou/">Indiana University Bloomington</a> <br>(<a
+href="https://twitter.com/xzhou">@xzhou</a>, <a
+href="mailto:zhou.xiaoyong@gmail.com">zhou.xiaoyong@gmail.com</a>)</p>
+
+<p><a href="http://homes.soic.indiana.edu/luyixing">Luyi Xing</a> of Indiana
+University Bloomington (<a
+href="mailto:xingluyi@gmail.com">xingluyi@gmail.com</a>)</p>
+
+<p>Yeonjoon Lee of Indiana University Bloomington (<a
+href="mailto:luc2yj@gmail.com">luc2yj@gmail.com</a>)</p>
+
+<p><a href="http://www.informatics.indiana.edu/xw7/">Xiaofeng Wang</a> of
+Indiana University Bloomington (<a
+href="mailto:xw7@indiana.edu">xw7@indiana.edu</a>)</p>
+
+<p>Xinhui Han of Peking University (<a
+href="mailto:hanxinhui@pku.edu.cn">hanxinhui@pku.edu.cn</a>)</p>
+
+<p><a href="http://thejh.net/">Jann Horn</a> <a href="https://android-review.googlesource.com/#/c/98197/">
+<img style="vertical-align:middle;" src="../images/tiny-robot.png"
+alt="Green Droid Patch Symbol"
+title="This person contributed code that improved Android security">
+</a></p>
+
+<p>Robert Craig of <a href="https://www.nsa.gov/research/ia_research/">
+Trusted Systems Research Group</a>, US National Security Agency
+<a href="https://android-review.googlesource.com/#/q/owner:%22Robert+Craig+%253Crpcraig%2540tycho.ncsc.mil%253E%22+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png" alt="Patch Symbol"
+title="This person contributed code that improved Android security"></a></p>
+
+<p>Stephen Smalley of <a href="https://www.nsa.gov/research/ia_research/">
+Trusted Systems Research Group</a>, US National Security Agency
+<a href=
+"https://android-review.googlesource.com/#/q/owner:%22Stephen+Smalley+%253Csds%2540tycho.nsa.gov%253E%22+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
+alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
+
+<p><a href="http://www.linkedin.com/in/billcroberts">
+William Roberts</a> (<a href="mailto:bill.c.roberts@gmail.com">bill.c.roberts@gmail.com</a>)
+<a href=
+"https://android-review.googlesource.com/#/q/owner:bill.c.roberts%2540gmail.com+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
+alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
+
+<p>Scotty Bauer of University of Utah (<a href="mailto:sbauer@eng.utah.edu">sbauer@eng.utah.edu</a>)</p>
+
+<p><a href="http://www.cs.utah.edu/~rsas/">Raimondas Sasnauskas</a> of University of Utah</p>
+
+<p><a href="http://www.subodh.io">Subodh Iyengar</a> of <a href="https://www.facebook.com">Facebook</a></p>
+
+<p><a href="http://www.shackleton.io/">Will Shackleton</a> of <a href="https://www.facebook.com">Facebook</a></p>
+
+<p>Kunal Patel of <a href="https://www.samsungknox.com/">Samsung KNOX Security Team</a> (<a href="mailto:kunal.patel1@samsung.com">kunal.patel1@samsung.com</a>)</p>
+
+<p>Sebastian Brenza</p>
+
+<p>Wang Tao of <a href="http://xteam.baidu.com">Baidu X-Team</a> (<a href="mailto:wintao@gmail.com">wintao@gmail.com</a>)</p>
+
+<p><a href="http://www.linkedin.com/in/danamodio">Dan Amodio</a> of <a href="https://www.aspectsecurity.com/">Aspect Security</a> (<a href="https://twitter.com/DanAmodio">@DanAmodio</a>)</p>
+
+<p><a href="http://davidmurdoch.com">David Murdoch</a></p>
+
+<p>Alexandru Gheorghita</p>
+
+<p>Mathew Solnik (<a href="https://twitter.com/msolnik">@msolnik</a>)</p>
+
+<p>Marc Blanchou (<a href="https://twitter.com/marcblanchou">@marcblanchou</a>)</p>
+
+<p>Wang Yu of <a href="http://xteam.baidu.com">Baidu X-Team</a> (<a href="https://twitter.com/xi4oyu">@xi4oyu</a>)</p>
+
+<p>Zhang Dong Hui of <a href="http://xteam.baidu.com">Baidu X-Team</a> (<a href="http://weibo.com/shineastdh">shineastdh</a>)</p>
+
+<p>Alex Park (<a href="https://twitter.com/saintlinu">@saintlinu</a>)</p>
+
+<p><a href="http://www.sonymobile.com">Sony Mobile</a></p>
+
+<p><a href="https://twitter.com/isciurus">Andrey Labunets</a> of <a href="https://www.facebook.com">Facebook</a></p>
+
+<p>Imre Rad of <a href="http://www.search-lab.hu/">Search-Lab Ltd.</a></p>
+
+</div>
+
+<h2 id=2013>2013</h2>
+
+<div style="LINE-HEIGHT:25px;">
+
+<p>Jon Sawyer of <a href="http://appliedcybersecurity.com/">Applied Cybersecurity LLC
+</a> (<a href="mailto:jon@cunninglogic.com">jon@cunninglogic.com</a>)</p>
+
+<p>Joshua J. Drake of <a href="http://www.accuvant.com/">Accuvant LABS
+</a> (<a href="https://twitter.com/jduck">@jduck</a>)
+<a href="https://android-review.googlesource.com/#/q/change:72228+OR+change:72229">
+<img style="vertical-align:middle" src="../images/patchreward.png"
+alt="Patch Rewards Symbol" title="This person qualified for the Patch Rewards program!"></a></p>
+
+<p>Ruben Santamarta of IOActive
+(<a href="https://twitter.com/reversemode">@reversemode</a>)</p>
+
+<p>Lucas Yang (amadoh4ck) of
+<a href="http://raonsecurity.com/">RaonSecurity</a>
+(<a href="mailto:amadoh4ck@gmail.com">amadoh4ck@gmail.com</a>)</p>
+
+<p><a href="https://tsarstva.bg/sh/">Ivaylo Marinkov</a>
+of <a href="http://www.ecommera.com/">eCommera</a> <br>
+(<a href="mailto:ivo@tsarstva.bg">ivo@tsarstva.bg</a>)</p>
+
+<p><a href="http://roeehay.blogspot.com/">Roee Hay</a>
+<br>(<a href="https://twitter.com/roeehay">@roeehay</a>,
+<a href="mailto:roeehay@gmail.com">roeehay@gmail.com</a>)</p>
+
+<p>Qualcomm Product Security Initiative</p>
+
+<p><a href="https://lacklustre.net/">Mike Ryan</a> of
+<a href="https://isecpartners.com/">iSEC Partners</a>
+<br>(<a href="https://twitter.com/mpeg4codec">@mpeg4codec</a>,
+<a href="mailto:mikeryan@isecpartners.com">mikeryan@isecpartners.com
+</a>)</p>
+
+<p><a href="http://cryptoonline.com/">Muhammad Naveed</a>
+of <a href="http://illinois.edu/">University of Illinois
+at Urbana-Champaign</a>
+<br>(<a href="mailto:naveed2@illinois.edu">naveed2@illinois.edu</a>)</p>
+
+<p>Robert Craig of <a href="https://www.nsa.gov/research/ia_research/">
+Trusted Systems Research Group</a>, US National Security Agency
+<a href="https://android-review.googlesource.com/#/q/owner:%22Robert+Craig+%253Crpcraig%2540tycho.ncsc.mil%253E%22+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png" alt="Patch Symbol"
+title="This person contributed code that improved Android security"></a></p>
+
+<p>Stephen Smalley of <a href="https://www.nsa.gov/research/ia_research/">
+Trusted Systems Research Group</a>, US National Security Agency
+<a href=
+"https://android-review.googlesource.com/#/q/owner:%22Stephen+Smalley+%253Csds%2540tycho.nsa.gov%253E%22+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
+alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
+
+<p><a href="http://www.linkedin.com/in/billcroberts">
+William Roberts</a> (<a href="mailto:bill.c.roberts@gmail.com">bill.c.roberts@gmail.com</a>)
+<a href=
+"https://android-review.googlesource.com/#/q/owner:bill.c.roberts%2540gmail.com+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
+alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
+
+<p><a href="http://roeehay.blogspot.com/">Roee Hay</a>
+<br>(<a href="https://twitter.com/roeehay">@roeehay</a>,
+<a href="mailto:roeehay@gmail.com">roeehay@gmail.com</a>)</p>
+
+<p><a href="http://homes.soic.indiana.edu/luyixing">Luyi Xing</a> of Indiana
+University Bloomington (<a
+href="mailto:xingluyi@gmail.com">xingluyi@gmail.com</a>)</p>
+
+<p>Xiaorui Pan of Indiana University Bloomington (<a href="mailto:eagle200467@gmail.com">eagle200467@gmail.com</a>)<p>
+
+<p>XiaoFeng Wang of Indiana University Bloomington (<a href="mailto:xw7@indiana.edu">xw7@indiana.edu</a>)</p>
+
+<p>Kan Yuan</p>
+
+</div>
+<h2 id=2012>2012</h2>
+
+<div style="LINE-HEIGHT:25px;">
+
+<p>Robert Craig of <a href="https://www.nsa.gov/research/ia_research/">
+Trusted Systems Research Group</a>, US National Security Agency
+<a href="https://android-review.googlesource.com/#/q/owner:%22Robert+Craig+%253Crpcraig%2540tycho.ncsc.mil%253E%22+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png" alt="Patch Symbol"
+title="This person contributed code that improved Android security"></a></p>
+
+<p>Stephen Smalley of <a href="https://www.nsa.gov/research/ia_research/">
+Trusted Systems Research Group</a>, US National Security Agency
+<a href=
+"https://android-review.googlesource.com/#/q/owner:%22Stephen+Smalley+%253Csds%2540tycho.nsa.gov%253E%22+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
+alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
+
+<p><a href="http://www.linkedin.com/in/billcroberts">
+William Roberts</a> (<a href="mailto:bill.c.roberts@gmail.com">bill.c.roberts@gmail.com</a>)
+<a href=
+"https://android-review.googlesource.com/#/q/owner:bill.c.roberts%2540gmail.com+status:merged">
+<img style="vertical-align:middle" src="../images/tiny-robot.png"
+alt="Patch Symbol" title="This person contributed code that improved Android security"></a></p>
+
+<p><a href="http://thejh.net/">Jann Horn</a></p>
+
+<p>Ravishankar Borgaonkar of TU Berlin
+(<a href="https://twitter.com/raviborgaonkar">@raviborgaonkar</a>)</p>
+
+<p><a href="http://roeehay.blogspot.com/">Roee Hay</a>
+<br>(<a href="https://twitter.com/roeehay">@roeehay</a>,
+<a href="mailto:roeehay@gmail.com">roeehay@gmail.com</a>)</p>
+
+<p>David Weinstein of <a href="https://viaforensics.com/">viaForensics</a> (<a href="https://twitter.com/insitusec">@insitusec</a>)</p>
+
+</div>
+
+<h2 id=2011>2011</h2>
+
+<div style="LINE-HEIGHT:25px;">
+
+<p>Collin Mulliner of <a href="http://www.mulliner.org/collin/academic">MUlliNER.ORG</a> (<a href="https://twitter.com/collinrm">@collinrm</a>)</p>
+
+</div>
+
+<h2 id=2009>2009</h2>
+
+<div style="LINE-HEIGHT:25px;">
+
+<p>Collin Mulliner of <a href="http://www.mulliner.org/collin/academic">MUlliNER.ORG</a> (<a href="https://twitter.com/collinrm">@collinrm</a>)</p>
+
+<p>Charlie Miller (<a href="https://twitter.com/0xcharlie">@0xcharlie</a>)</p>
+
+</div>
+
+<br>
+<p><small>If you have reported a vulnerability prior to 2014 and want to be
+included on this list, or to report a vulnerability in Android, contact <a href="mailto:security@android.com">security@android.com</a></small></p>
diff --git a/src/security/overview/app-security.jd b/src/security/overview/app-security.jd
new file mode 100644
index 0000000..f25f067
--- /dev/null
+++ b/src/security/overview/app-security.jd
@@ -0,0 +1,345 @@
+page.title=Application security
+@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="elements-of-applications">Elements of Applications</h2>
+<p>Android provides an open source platform and application environment for mobile
+ devices. The core operating system is based on the Linux kernel. Android
+ applications are most often written in the Java programming language and run in
+ the Dalvik virtual machine. However, applications can also be written in native
+ code. Applications are installed from a single file with the .apk file
+ extension.</p>
+<p>The main Android application building blocks are:</p>
+<ul>
+ <li>
+ <p><strong>AndroidManifest.xml</strong>: The <a href="https://developer.android.com/guide/topics/manifest/manifes
+t-intro.html">AndroidManifest.xml</a> file is the control file that tells the system what to do with
+ all the top-level components (specifically activities, services, broadcast
+ receivers, and content providers described below) in an application. This also
+ specifies which permissions are required.</p>
+ </li>
+ <li>
+ <p><strong>Activities</strong>: An <a href="https://developer.android.com/guide/topics/fundamentals/activities.htm
+l">Activity</a> is, generally, the code for a single, user-focused task. It usually
+ includes displaying a UI to the user, but it does not have to -- some
+ Activities never display UIs. Typically, one of the application's Activities
+ is the entry point to an application.</p>
+ </li>
+ <li>
+ <p><strong>Services</strong>: A <a href="https://developer.android.com/guide/topics/fundamentals/services.html">Service</a> is a body of code that runs in the background. It can run in its own process,
+ or in the context of another application's process. Other components "bind" to
+ a Service and invoke methods on it via remote procedure calls. An example of a
+ Service is a media player: even when the user quits the media-selection UI, the
+ user probably still intends for music to keep playing. A Service keeps the
+ music going even when the UI has completed.</p>
+ </li>
+ <li>
+ <p><strong>Broadcast Receiver</strong>: A <a href="https://developer.android.com/reference/android/content/Broad
+castReceiver.html">BroadcastReceiver</a> is an object that is instantiated when an IPC mechanism
+ known as an <a href="https://developer.android.com/reference/android/content/Intent.html">Intent</a> is issued by the operating system or another application. An application may
+ register a receiver for the low battery message, for example, and change its
+ behavior based on that information.</p>
+ </li>
+</ul>
+<h2 id="the-android-permission-model-accessing-protected-apis">The Android Permission Model: Accessing Protected APIs</h2>
+<p>All applications on Android run in an Application Sandbox, described earlier in this document.
+ By default, an Android application can only access a limited range of system
+ resources. The system manages Android application access to resources that, if
+ used incorrectly or maliciously, could adversely impact the user experience,
+ the network, or data on the device.</p>
+<p>These restrictions are implemented in a variety of different forms. Some
+ capabilities are restricted by an intentional lack of APIs to the sensitive
+ functionality (e.g. there is no Android API for directly manipulating the SIM
+ card). In some instances, separation of roles provides a security measure, as
+ with the per-application isolation of storage. In other instances, the
+ sensitive APIs are intended for use by trusted applications and protected
+ through a security mechanism known as Permissions.</p>
+<p>These protected APIs include:</p>
+<ul>
+ <li>Camera functions</li>
+ <li>Location data (GPS)</li>
+ <li>Bluetooth functions</li>
+ <li>Telephony functions</li>
+ <li>SMS/MMS functions</li>
+ <li>Network/data connections</li>
+</ul>
+<p>These resources are only accessible through the operating system. To make use
+ of the protected APIs on the device, an application must define the
+ capabilities it needs in its manifest. When preparing to install an
+ application, the system displays a dialog to the user that indicates the
+ permissions requested and asks whether to continue the installation. If the
+ user continues with the installation, the system accepts that the user has
+ granted all of the requested permissions. The user can not grant or deny
+ individual permissions -- the user must grant or deny all of the requested
+ permissions as a block.</p>
+<p>Once granted, the permissions are applied to the application as long as it is
+ installed. To avoid user confusion, the system does not notify the user again
+ of the permissions granted to the application, and applications that are
+ included in the core operating system or bundled by an OEM do not request
+ permissions from the user. Permissions are removed if an application is
+ uninstalled, so a subsequent re-installation will again result in display of
+ permissions.</p>
+<p>Within the device settings, users are able to view permissions for applications
+ they have previously installed. Users can also turn off some functionality
+ globally when they choose, such as disabling GPS, radio, or wi-fi.</p>
+<p>In the event that an application attempts to use a protected feature which has
+ not been declared in the application's manifest, the permission failure will
+ typically result in a security exception being thrown back to the application.
+ Protected API permission checks are enforced at the lowest possible level to
+ prevent circumvention. An example of the user messaging when an application is
+ installed while requesting access to protected APIs is shown in <em>Figure 2</em>.</p>
+<p>The system default permissions are described at <a href="https://developer.android.com/reference/android/Manifest.permission.html">https://developer.android.com/reference/android/Manifest.permission.html</a>.
+ Applications may declare their own permissions for other applications to use.
+ Such permissions are not listed in the above location.</p>
+<p>When defining a permission a protectionLevel attribute tells the system how the
+ user is to be informed of applications requiring the permission, or who is
+ allowed to hold a permission. Details on creating and using application
+ specific permissions are described at <a href="https://develo
+per.android.com/guide/topics/security/security.html">https://developer.android.com/guide/topics/security/security.html</a>.</p>
+<p>There are some device capabilities, such as the ability to send SMS broadcast
+ intents, that are not available to third-party applications, but that may be
+ used by applications pre-installed by the OEM. These permissions use the
+ signatureOrSystem permission.</p>
+<h2 id="how-users-understand-third-party-applications">How Users Understand Third-Party Applications</h2>
+<p>Android strives to make it clear to users when they are interacting with
+ third-party applications and inform the user of the capabilities those
+ applications have. Prior to installation of any application, the user is shown
+ a clear message about the different permissions the application is requesting.
+ After install, the user is not prompted again to confirm any permissions.</p>
+<p>There are many reasons to show permissions immediately prior to installation
+ time. This is when user is actively reviewing information about the
+ application, developer, and functionality to determine whether it matches their
+ needs and expectations. It is also important that they have not yet
+ established a mental or financial commitment to the app, and can easily compare
+ the application to other alternative applications.</p>
+<p>Some other platforms use a different approach to user notification, requesting
+ permission at the start of each session or while applications are in use. The
+ vision of Android is to have users switching seamlessly between applications at
+ will. Providing confirmations each time would slow down the user and prevent
+ Android from delivering a great user experience. Having the user review
+ permissions at install time gives the user the option to not install the
+ application if they feel uncomfortable.</p>
+<p>Also, many user interface studies have shown that over-prompting the user
+ causes the user to start saying "OK" to any dialog that is shown. One of
+ Android's security goals is to effectively convey important security
+ information to the user, which cannot be done using dialogs that the user will
+ be trained to ignore. By presenting the important information once, and only
+ when it is important, the user is more likely to think about what they are
+ agreeing to.</p>
+<p>Some platforms choose not to show any information at all about application
+ functionality. That approach prevents users from easily understanding and
+ discussing application capabilities. While it is not possible for all users to
+ always make fully informed decisions, the Android permissions model makes
+ information about applications easily accessible to a wide range of users. For
+ example, unexpected permissions requests can prompt more sophisticated users to
+ ask critical questions about application functionality and share their concerns
+ in places such as <a href="htts://play.google.com">Google Play</a> where they
+ are visible to all users.</p>
+<table>
+ <tr>
+ <td><strong>Permissions at Application Install -- Google Maps</strong></td>
+ <td><strong>Permissions of an Installed Application -- Gmail</strong></td>
+ </tr>
+ <tr>
+ <td><img alt="Permissions at Application Install -- Google Maps" width=250
+src="../images/image_install.png" /></td>
+ <td><img alt="Permissions of an Installed Application -- Gmail" width=250
+src="../images/image_gmail_installed.png" id="figure1" /></td>
+ </tr>
+</table>
+<p class="img-caption">
+ <strong>Figure 1.</strong> Display of permissions for applications
+</p>
+<h2 id="interprocess-communication">Interprocess Communication</h2>
+<p>Processes can communicate using any of the traditional UNIX-type mechanisms.
+ Examples include the filesystem, local sockets, or signals. However, the Linux
+ permissions still apply.</p>
+<p>Android also provides new IPC mechanisms:</p>
+<ul>
+ <li>
+ <p><strong>Binder</strong>: A lightweight capability-based remote procedure call mechanism
+ designed for high performance when performing in-process and cross-process
+ calls. Binder is implemented using a custom Linux driver. See <a href="https://developer
+.android.com/reference/android/os/Binder.html">https://developer.android.com/reference/android/os/Binder.html</a>.</p>
+ </li>
+ <li>
+ <p><strong>Services</strong>: Services (discussed above) can provide interfaces directly
+ accessible using binder.</p>
+ </li>
+ <li>
+ <p><strong>Intents</strong>: An Intent is a simple message object that represents an
+ "intention" to do something. For example, if your application wants to display
+ a web page, it expresses its "Intent" to view the URL by creating an Intent
+ instance and handing it off to the system. The system locates some other piece
+ of code (in this case, the Browser) that knows how to handle that Intent, and
+ runs it. Intents can also be used to broadcast interesting events (such as a
+ notification) system-wide. See
+ [https://developer.android.com/reference/android/content/Intent.html](https://developer.android.com/reference/android/content/Intent.html.</p>
+ </li>
+ <li>
+ <p><strong>ContentProviders</strong>: A ContentProvider is a data storehouse that provides
+ access to data on the device; the classic example is the ContentProvider that
+ is used to access the user's list of contacts. An application can access data
+ that other applications have exposed via a ContentProvider, and an application
+ can also define its own ContentProviders to expose data of its own. See <a href="https://developer.android.com/reference/android/content/ContentProvider.html">https://developer.android.com/reference/android/content/ContentProvider.html</a>.</p>
+ </li>
+</ul>
+<p>While it is possible to implement IPC using other mechanisms such as network
+ sockets or world-writable files, these are the recommended Android IPC
+ frameworks. Android developers will be encouraged to use best practices around
+ securing users' data and avoiding the introduction of security vulnerabilities.</p>
+<h2 id="cost-sensitive-apis">Cost-Sensitive APIs</h2>
+<p>A cost sensitive API is any function that might generate a cost for the user or
+ the network. The Android platform has placed cost sensitive APIs in the list of
+ protected APIs controlled by the OS. The user will have to grant explicit
+ permission to third-party applications requesting use of cost sensitive APIs.
+ These APIs include:</p>
+<ul>
+ <li>Telephony</li>
+ <li>SMS/MMS</li>
+ <li>Network/Data</li>
+ <li>In-App Billing</li>
+ <li>NFC Access</li>
+</ul>
+<p> Android 4.2 adds further control on the use of SMS. Android will provide a
+ notification if an application attempts to send SMS to a short code that uses
+ premium services which might cause additional charges. The user can choose
+ whether to allow the application to send the message or block it. </p>
+<h2 id="sim-card-access">SIM Card Access</h2>
+<p>Low level access to the SIM card is not available to third-party apps. The OS
+ handles all communications with the SIM card including access to personal
+ information (contacts) on the SIM card memory. Applications also cannot access
+ AT commands, as these are managed exclusively by the Radio Interface Layer
+ (RIL). The RIL provides no high level APIs for these commands.</p>
+<h2 id="personal-information">Personal Information</h2>
+<p>Android has placed APIs that provide access to user data into the set of
+ protected APIs. With normal usage, Android devices will also accumulate user
+ data within third-party applications installed by users. Applications that
+ choose to share this information can use Android OS permission checks to
+ protect the data from third-party applications.</p>
+<img alt="Access to sensitive user data available only through protected
+APIs" src="../images/permissions_check.png" id="figure2" />
+<p class="img-caption">
+ <strong>Figure 2.</strong> Access to sensitive user data is available only through protected APIs
+</p>
+<p>System content providers that are likely to contain personal or personally
+ identifiable information such as contacts and calendar have been created with
+ clearly identified permissions. This granularity provides the user with clear
+ indication of the types of information that may be provided to the application.
+ During installation, a third-party application may request permission to
+ access these resources. If permission is granted, the application can be
+ installed and will have access to the data requested at any time when it is
+ installed.</p>
+<p>Any applications which collect personal information will, by default, have that
+ data restricted only to the specific application. If an application chooses to
+ make the data available to other applications though IPC, the application
+ granting access can apply permissions to the IPC mechanism that are enforced by
+ the operating system.</p>
+<h2 id="sensitive-data-input-devices">Sensitive Data Input Devices</h2>
+<p>Android devices frequently provide sensitive data input devices that allow
+ applications to interact with the surrounding environment, such as camera,
+ microphone or GPS. For a third-party application to access these devices, it
+ must first be explicitly provided access by the user through the use of Android
+ OS Permissions. Upon installation, the installer will prompt the user
+ requesting permission to the sensor by name.</p>
+<p>If an application wants to know the user's location, the application requires a
+ permission to access the user's location. Upon installation, the installer will
+ prompt the user asking if the application can access the user's location. At
+ any time, if the user does not want any application to access their location,
+ then the user can run the "Settings" application, go to "Location & Security",
+ and uncheck the "Use wireless networks" and "Enable GPS satellites". This will
+ disable location based services for all applications on the user's device.</p>
+<h2 id="device-metadata">Device Metadata</h2>
+<p>Android also strives to restrict access to data that is not intrinsically
+ sensitive, but may indirectly reveal characteristics about the user, user
+ preferences, and the manner in which they use a device.</p>
+<p>By default applications do not have access to operating system logs,
+ browser history, phone number, or hardware / network identification
+ information. If an application requests access to this information at install
+ time, the installer will prompt the user asking if the application can access
+ the information. If the user does not grant access, the application will not be
+ installed.</p>
+<h2 id="application-signing">Application Signing</h2>
+<p>Code signing allows developers to identify the author of the application and to
+ update their application without creating complicated interfaces and
+ permissions. Every application that is run on the Android platform must be
+ signed by the developer. Applications that attempt to install without being
+ signed will rejected by either Google Play or the package installer on
+ the Android device.</p>
+<p>On Google Play, application signing bridges the trust Google has with the
+ developer and the trust the developer has with their application. Developers
+ know their application is provided, unmodified to the Android device; and
+ developers can be held accountable for behavior of their application.</p>
+<p>On Android, application signing is the first step to placing an application in
+ its Application Sandbox. The signed application certificate defines which user
+ id is associated with which application; different applications run under
+ different user IDs. Application signing ensures that one application cannot
+ access any other application except through well-defined IPC.</p>
+<p>When an application (APK file) is installed onto an Android device, the Package
+ Manager verifies that the APK has been properly signed with the certificate
+ included in that APK. If the certificate (or, more accurately, the public key
+ in the certificate) matches the key used to sign any other APK on the device,
+ the new APK has the option to specify in the manifest that it will share a UID
+ with the other similarly-signed APKs.</p>
+<p>Applications can be signed by a third-party (OEM, operator, alternative market)
+ or self-signed. Android provides code signing using self-signed certificates
+ that developers can generate without external assistance or permission.
+ Applications do not have to be signed by a central authority. Android currently
+ does not perform CA verification for application certificates.</p>
+<p>Applications are also able to declare security permissions at the Signature
+ protection level, restricting access only to applications signed with the same
+ key while maintaining distinct UIDs and Application Sandboxes. A closer
+ relationship with a shared Application Sandbox is allowed via the <a href="https://developer.android.com/guide/topics/manifest/manifest-element.html#uid">shared UID
+ feature</a> where two or more applications signed with same developer key can
+ declare a shared UID in their manifest.</p>
+<h2 id="app-verification">Application Verification</h2>
+<p> Android 4.2 and later support application verification. Users can choose to
+ enable “Verify Apps" and have applications evaluated by an application verifier
+ prior to installation. App verification can alert the user if they try to
+ install an app that might be harmful; if an application is especially bad, it
+ can block installation. </p>
+<h2 id="digital-rights-management">Digital Rights Management</h2>
+<p>The Android platform provides an extensible DRM framework that lets
+ applications manage rights-protected content according to the license
+ constraints that are associated with the content. The DRM framework supports
+ many DRM schemes; which DRM schemes a device supports is left to the device
+ manufacturer.</p>
+<p>The <a href="https://developer.android.com/reference/android/drm/package-summary.html">Android DRM
+ framework</a> is implemented in two architectural layers (see figure below):</p>
+<ul>
+ <li>
+ <p>A DRM framework API, which is exposed to applications through the Android
+ application framework and runs through the Dalvik VM for standard applications.</p>
+ </li>
+ <li>
+ <p>A native code DRM manager, which implements the DRM framework and exposes an
+ interface for DRM plug-ins (agents) to handle rights management and decryption
+ for various DRM schemes</p>
+ </li>
+</ul>
+<p><img alt="Architecture of Digital Rights Management on Android
+platform" src="../../../images/ape_fwk_drm_2.png" id="figure3" /></p>
+<p class="img-caption">
+ <strong>Figure 3.</strong> Architecture of Digital Rights Management on Android platform
+</p>
diff --git a/src/security/overview/index.jd b/src/security/overview/index.jd
new file mode 100644
index 0000000..6b00c55
--- /dev/null
+++ b/src/security/overview/index.jd
@@ -0,0 +1,80 @@
+page.title=Security overview
+@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="android-security-program-overview">Security Program Overview</h2>
+<p>Early on in development, the core Android development team recognized that a
+ robust security model was required to enable a vigorous ecosystem of
+ applications and devices built on and around the Android platform and supported
+ by cloud services. As a result, through its entire development lifecycle,
+ Android has been subjected to a professional security program. The Android team
+ has had the opportunity to observe how other mobile, desktop, and server platforms
+ prevented and reacted to security issues and built a security
+ program to address weak points observed in other offerings.</p>
+<p>The key components of the Android Security Program include:</p>
+<ul>
+ <li><strong>Design Review</strong>: The Android security process begins early in the
+ development lifecycle with the creation of a rich and configurable security
+ model and design. Each major feature of the platform is reviewed by engineering
+ and security resources, with appropriate security controls integrated into the
+ architecture of the system.</li>
+ <li><strong>Penetration Testing and Code Review</strong>: During the development of the
+ platform, Android-created and open source components are subject to vigorous
+ security reviews. These reviews are performed by the Android Security Team,
+ Google’s Information Security Engineering team, and independent security
+ consultants. The goal of these reviews is to identify weaknesses and possible
+ vulnerabilities well before the platform is open sourced, and to simulate the
+ types of analysis that will be performed by external security experts upon
+ release.</li>
+ <li><strong>Open Source and Community Review</strong>: The Android Open Source Project enables
+ broad security review by any interested party. Android also uses open source
+ technologies that have undergone significant external security review,
+ such as the Linux kernel. Google Play provides a forum for users and companies
+ to provide information about specific applications directly to users.</li>
+ <li><strong>Incident Response</strong>: Even with all of these precautions, security issues
+ may occur after shipping, which is why the Android project has created a
+ comprehensive security response process. A full-time Android security team
+ constantly monitors Android-specific and the general security community for
+ discussion of potential vulnerabilities. Upon the discovery of legitimate
+ issues, the Android team has a response process that enables the rapid
+ mitigation of vulnerabilities to ensure that potential risk to all Android
+ users is minimized. These cloud-supported responses can include updating the
+ Android platform (over-the-air updates), removing applications from Google
+ Play, and removing applications from devices in the field.</li>
+</ul>
+<h2 id="android-platform-security-architecture">Platform Security Architecture</h2>
+<p>Android seeks to be the most secure and usable operating system for mobile
+ platforms by re-purposing traditional operating system security controls to:</p>
+<ul>
+ <li>Protect user data</li>
+ <li>Protect system resources (including the network)</li>
+ <li>Provide application isolation</li>
+</ul>
+<p>To achieve these objectives, Android provides these key security features:</p>
+<ul>
+ <li>Robust security at the OS level through the Linux kernel</li>
+ <li>Mandatory application sandbox for all applications</li>
+ <li>Secure interprocess communication</li>
+ <li>Application signing</li>
+ <li>Application-defined and user-granted permissions</li>
+</ul>
diff --git a/src/security/overview/kernel-security.jd b/src/security/overview/kernel-security.jd
new file mode 100644
index 0000000..326ac18
--- /dev/null
+++ b/src/security/overview/kernel-security.jd
@@ -0,0 +1,188 @@
+page.title=System and kernel security
+@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>
+
+<p>At the operating system level, the Android platform provides the security of
+ the Linux kernel, as well as a secure inter-process communication (IPC)
+ facility to enable secure communication between applications running in
+ different processes. These security features at the OS level ensure that even
+ native code is constrained by the Application Sandbox. Whether that code is
+ the result of included application behavior or a exploitation of an application
+ vulnerability, the system would prevent the rogue application from harming
+ other applications, the Android system, or the device itself.</p>
+<h3 id="linux-security">Linux Security</h3>
+<p>The foundation of the Android platform is the Linux kernel. The Linux kernel
+ itself has been in widespread use for years, and is used in millions of
+ security-sensitive environments. Through its history of constantly being
+ researched, attacked, and fixed by thousands of developers, Linux has become a
+ stable and secure kernel trusted by many corporations and security
+ professionals.</p>
+<p>As the base for a mobile computing environment, the Linux kernel provides
+ Android with several key security features, including:</p>
+<ul>
+ <li>A user-based permissions model</li>
+ <li>Process isolation</li>
+ <li>Extensible mechanism for secure IPC</li>
+ <li>The ability to remove unnecessary and potentially insecure parts of the kernel</li>
+</ul>
+<p>As a multiuser operating system, a fundamental security objective of the Linux
+ kernel is to isolate user resources from one another. The Linux security
+ philosophy is to protect user resources from one another. Thus, Linux:</p>
+<ul>
+ <li>Prevents user A from reading user B's files</li>
+ <li>Ensures that user A does not exhaust user B's memory</li>
+ <li>Ensures that user A does not exhaust user B's CPU resources</li>
+ <li>Ensures that user A does not exhaust user B's devices (e.g. telephony, GPS,
+ bluetooth)</li>
+</ul>
+<h3 id="the-application-sandbox">The Application Sandbox</h3>
+<p>The Android platform takes advantage of the Linux user-based protection as a
+ means of identifying and isolating application resources. The Android system
+ assigns a unique user ID (UID) to each Android application and runs it as that user
+ in a separate process. This approach is different from other operating systems
+ (including the traditional Linux configuration), where multiple applications
+ run with the same user permissions.</p>
+<p>This sets up a kernel-level Application Sandbox. The kernel enforces security
+ between applications and the system at the process level through standard Linux
+ facilities, such as user and group IDs that are assigned to applications. By
+ default, applications cannot interact with each other and applications have
+ limited access to the operating system. If application A tries to do something
+ malicious like read application B's data or dial the phone without permission
+ (which is a separate application), then the operating system protects against
+ this because application A does not have the appropriate user privileges. The
+ sandbox is simple, auditable, and based on decades-old UNIX-style user
+ separation of processes and file permissions.</p>
+<p>Since the Application Sandbox is in the kernel, this security model extends to
+ native code and to operating system applications. All of the software above the
+ kernel in <em>Figure 1</em>, including operating system libraries, application
+ framework, application runtime, and all applications run within the Application
+ Sandbox. On some platforms, developers are constrained to a specific
+ development framework, set of APIs, or language in order to enforce security.
+ On Android, there are no restrictions on how an application can be written that
+ are required to enforce security; in this respect, native code is just as
+ secure as interpreted code.</p>
+<p>In some operating systems, memory corruption errors generally lead to
+ completely compromising the security of the device. This is not the case in
+ Android due to all applications and their resources being sandboxed at the OS
+ level. A memory corruption error will only allow arbitrary code execution in
+ the context of that particular application, with the permissions established by
+ the operating system.</p>
+<p>Like all security features, the Application Sandbox is not unbreakable.
+ However, to break out of the Application Sandbox in a properly configured
+ device, one must compromise the security of the the Linux kernel.</p>
+<h3 id="system-partition-and-safe-mode">System Partition and Safe Mode</h3>
+<p>The system partition contains Android's kernel as well as the operating system
+ libraries, application runtime, application framework, and applications. This
+ partition is set to read-only. When a user boots the device into Safe Mode,
+ only core Android applications are available. This ensures that the user can
+ boot their phone into an environment that is free of third-party software.</p>
+<h3 id="filesystem-permissions">Filesystem Permissions</h3>
+<p>In a UNIX-style environment, filesystem permissions ensure that one user cannot
+ alter or read another user's files. In the case of Android, each application
+ runs as its own user. Unless the developer explicitly exposes files to other
+ applications, files created by one application cannot be read or altered by
+ another application.</p>
+<h3 id="se-linux">Security-Enhanced Linux</h3>
+<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}security/selinux/index.html">Validating
+ Security-Enhanced Linux in
+ Android</a> for details.</p>
+<h3 id="crypto">Cryptography</h3>
+<p> Android provides a set of cryptographic APIs for use by applications. These
+ include implementations of standard and commonly used cryptographic primitives
+ such as AES, RSA, DSA, and SHA. Additionally, APIs are provided for higher level
+ protocols such as SSL and HTTPS. </p>
+<p> Android 4.0 introduced the <a href="http://developer.android.com/reference/android/security/KeyChain.html">KeyChain</a> class to allow applications to use the system credential storage for private
+ keys and certificate chains. </p>
+<h3>Rooting of Devices</h3>
+<p> By default, on Android only the kernel and a small subset of the core
+ applications run with root permissions. Android does not prevent a user or
+ application with root permissions from modifying the operating system, kernel,
+ and any other application. In general, root has full access to all
+ applications and all application data. Users that change the permissions on an
+ Android device to grant root access to applications increase the security
+ exposure to malicious applications and potential application flaws. </p>
+<p> The ability to modify an Android device they own is important to developers
+ working with the Android platform. On many Android devices users have the
+ ability to unlock the bootloader in order to allow installation of an alternate
+ operating system. These alternate operating systems may allow an owner to gain
+ root access for purposes of debugging applications and system components or to
+ access features not presented to applications by Android APIs. </p>
+<p> On some devices, a person with physical control of a device and a USB cable is
+ able to install a new operating system that provides root privileges to the
+ user. To protect any existing user data from compromise the bootloader unlock
+ mechanism requires that the bootloader erase any existing user data as part of
+ the unlock step. Root access gained via exploiting a kernel bug or security
+ hole can bypass this protection. </p>
+<p> Encrypting data with a key stored on-device does not protect the application
+ data from root users. Applications can add a layer of data protection using
+ encryption with a key stored off-device, such as on a server or a user
+ password. This approach can provide temporary protection while the key is not
+ present, but at some point the key must be provided to the application and it
+ then becomes accessible to root users. </p>
+<p> A more robust approach to protecting data from root users is through the use of
+ hardware solutions. OEMs may choose to implement hardware solutions that limit
+ access to specific types of content such as DRM for video playback, or the
+ NFC-related trusted storage for Google wallet. </p>
+<p> In the case of a lost or stolen device, full filesystem encryption on Android
+ devices uses the device password to protect the encryption key, so modifying
+ the bootloader or operating system is not sufficient to access user data
+ without the user’s device password. </p>
+<h3>User Security Features</h3>
+<h4 id="filesystem-encryption">Filesystem Encryption</h4>
+<p>Android 3.0 and later provides full filesystem encryption, so all user data can
+ be encrypted in the kernel using the dmcrypt implementation of AES128 with CBC
+ and ESSIV:SHA256. The encryption key is protected by AES128 using a key
+ derived from the user password, preventing unauthorized access to stored data
+ without the user device password. To provide resistance against systematic
+ password guessing attacks (e.g. “rainbow tables” or brute force), the
+ password is combined with a random salt and hashed repeatedly with SHA1 using
+ the standard PBKDF2 algorithm prior to being used to decrypt the filesystem
+ key. To provide resistance against dictionary password guessing attacks,
+ Android provides password complexity rules that can be set by the device
+ administrator and enforced by the operating system. Filesystem encryption
+ requires the use of a user password, pattern-based screen lock is not supported.</p>
+<p>More details on implementation of filesystem encryption are available at <a
+href="{@docRoot}security/encryption/index.html">Encryption</a>.</p>
+<h3 id="password-protection">Password Protection</h3>
+<p>Android can be configured to verify a user-supplied password prior to providing
+ access to a device. In addition to preventing unauthorized use of the device,
+ this password protects the cryptographic key for full filesystem encryption.</p>
+<p>Use of a password and/or password complexity rules can be required by a device
+ administrator.</p>
+<h3 id="device-administration">Device Administration</h3>
+<p>Android 2.2 and later provide the Android Device Administration API, which
+ provides device administration features at the system level. For example, the
+ built-in Android Email application uses the APIs to improve Exchange support.
+ Through the Email application, Exchange administrators can enforce password
+ policies — including alphanumeric passwords or numeric PINs — across
+ devices. Administrators can also remotely wipe (that is, restore factory
+ defaults on) lost or stolen handsets.</p>
+<p>In addition to use in applications included with the Android system, these APIs
+ are available to third-party providers of Device Management solutions. Details
+ on the API are provided at <a
+href="https://developer.android.com/guide/topics/admin/device-admin.html">Device
+Administration</a>.</p>
diff --git a/src/security/overview/updates-resources.jd b/src/security/overview/updates-resources.jd
new file mode 100644
index 0000000..8c8d047
--- /dev/null
+++ b/src/security/overview/updates-resources.jd
@@ -0,0 +1,258 @@
+page.title= Security updates and resources
+@jd:body
+
+<!--
+ Copyright 2015 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=android_security_bug_lifecycle>Android security bug lifecycle</h2>
+
+<p>The Android security team is responsible for managing security vulnerabilities
+discovered in the Android platform and many of the core Android apps bundled
+with Android devices.</p>
+
+<p>The Android security team finds security vulnerabilities through internal
+research and also responds to bugs reported by third parties. Sources of
+external bugs include issues reported through the <a
+href="https://code.google.com/p/android/issues/list">Android Open Source
+Project (AOSP) bug tracker</a>, published and pre-published academic research,
+upstream open source project maintainers, notifications from our device
+manufacturer partners, and publicly disclosed issues posted on blogs or social
+media.</p>
+
+<h2 id=report-issues>Reporting security issues</h2>
+
+<p>Any developer, Android user, or security researcher can notify the Android
+security team of potential security issues through the AOSP bug tracker <a
+href="https://code.google.com/p/android/issues/entry?template=Security%20bug%20report">Security
+bug report</a> template.</p>
+
+<p>Bugs marked as security issues are not externally visible, but they may
+eventually be made visible after the issue is evaluated or resolved. If you
+plan to submit a patch or Compatibility Test Suite (CTS) test to resolve a
+security issue, please attach it to the bug report and wait for a response
+before uploading the code to AOSP.</p>
+
+<p>If you need to reach the Android security team for a purpose other than
+reporting a vulnerability, please contact <a
+href="mailto:security@android.com">security@android.com</a>. The Android
+security team has a <a
+href="https://developer.android.com/security_at_android_dot_com.txt">PGP
+key</a> if you need to encrypt your message.</p>
+
+<h2 id=triaging_bugs>Triaging bugs</h2>
+
+<p>The first task in handling a security vulnerability is to identify the severity
+of the bug and which component of Android is affected. The severity determines
+how the issue is prioritized, and the component determines who fixes the bug,
+who is notified, and how the fix gets deployed to users.</p>
+
+<h3 id=severity>Severity</h3>
+
+<p>The severity of a bug generally reflects the potential harm that could occur if
+a bug was successfully exploited. Use the following criteria to determine the
+severity:</p>
+<p class="table-caption" id="severity-criteria">
+ <strong>Table 1.</strong> Severity ratings and associated consequences</p>
+<table>
+ <tr>
+ <th>Rating</th>
+ <th>Consequence of successful exploitation</th>
+ </tr>
+ <tr>
+ <td><strong>Critical</strong></td>
+ <td>
+<ul>
+<li>Remote privileged code execution (execution at a privilege level that
+third-party apps cannot obtain)
+<li>Local permanent device compromise (device cannot be repaired without
+re-flashing the entire operating system, such as a verified boot or Trusted
+Execution Environment/TEE compromise)
+<li>Remote permanent denial of service (inoperability, either completely permanent
+or requiring re-flashing the device)
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td><strong>High</strong></td>
+ <td>
+<ul>
+<li>Remote unprivileged code execution (execution at a privilege level that
+third-party apps can obtain through installation)
+<li>Local access to system/signature-level permission data or capabilities without
+permission
+<li>Local permanent denial-of-service (inoperability, either completely permanent
+or requiring re-flashing the device)
+<li>Remote temporary denial-of-service (remote hang or reboot)
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td><strong>Moderate</strong></td>
+ <td>
+<ul>
+<li>Access to "<a
+href="http://developer.android.com/guide/topics/manifest/permission-element.html#plevel">dangerous</a>"
+level permission data or capabilities without permission with an app installed
+on the device
+<li>Local temporary denial-of-service (can be resolved only through a factory
+reset)
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td><strong>Low</strong></td>
+ <td>
+<ul>
+<li>Access to "<a
+href="http://developer.android.com/guide/topics/manifest/permission-element.html#plevel">normal</a>"
+level permission capabilities without permission with an app installed on the
+device
+<li>Local temporary denial-of-service (can be resolved by booting the device into
+Safe Mode and removing the problem application)
+</ul>
+</td>
+ </tr>
+</table>
+
+<p>Though there are many types of software bugs outside of the security
+vulnerabilities detailed above, bugs reported are evaluated on a
+case-by-base basis to determine what security impact they have.</p>
+
+<p>The Android security team may also adjust the severity of a vulnerability if it
+is determined the risk to users is higher or lower than the guidelines suggest.
+For example, if a certain piece of data is available only to apps with "system"
+level access but the data itself is not sensitive, the Android security
+team may consider it only a low-severity vulnerability.</p>
+
+<h4 id=local_vs_remote>Local vs. remote</h4>
+
+<p>A remote attack vector indicates the bug could be exploited without installing
+an app or without physical access to the device. This includes bugs that could
+be triggered by browsing to a web page, reading an email, receiving an SMS
+message, or connecting to a hostile network. For the purpose of our severity
+ratings, the Android security team also considers "proximal" attack vectors as
+remote. These include bugs that can be exploited only by an attacker who is
+physically near the target device, for example a bug that requires sending
+malformed Wi-Fi or Bluetooth packets.</p>
+
+<p>Local attacks require the victim to install an app. For the purpose of severity
+ratings, the Android security team also considers physical attack vectors as
+local. These include bugs that can be exploited only by an attacker who has
+physical access to the device, for example a bug in a lock screen or one that
+requires plugging in a USB cable. The Android security team also considers
+NFC-based attacks as local.</p>
+
+<h4 id=high_privilege_levels>Severity of vulnerabilities that affect high privilege levels</h4>
+
+<p>The Android security team will usually drop the severity rating for a bug that
+already requires executing code at a high privilege level. For example, a bug
+in a kernel driver accessible only from a privileged service that
+requires first compromising the service. In this case, the Android security
+team may drop the severity from "high" to "moderate."</p>
+
+<h4 id=severity_of_kernel_compromises>Severity of kernel compromises</h4>
+
+<p>Whether a vulnerability that compromises the kernel is considered "high" or
+"critical" depends on the device and the version of Android. On devices with a
+TEE (or TrustZone) and <a
+href="{@docRoot}security/verifiedboot/index.html">verified
+boot</a>, a kernel compromise is considered "high" because exploiting it won't
+allow permanently affecting the operation of the device unless a vulnerability is
+discovered in the TEE or verified boot implementation. In general, if the
+result of a compromise can be remediated with a factory reset, it's "high" or
+lower.</p>
+
+<p>However, on older devices without verified boot, a kernel compromise can result
+in permanent device compromise if SELinux is disabled and the system partition
+is modified. On that device, a kernel compromise is considered "critical"
+because remediation requires re-flashing the device's firmware image.</p>
+
+<h3 id=affected_component>Affected component</h3>
+
+<p>The development team responsible for fixing the bug depends on which component
+the bug is in. It could be a core component of the Android platform, a kernel
+driver supplied by an original equipment manufacturer (OEM), or one of the
+pre-loaded apps on Nexus devices.</p>
+
+<p>Bugs in AOSP code are fixed by the Android engineering team. Low-severity bugs,
+bugs in certain components, or bugs that are already publicly known may be
+fixed directly in the publicly available AOSP master branch; otherwise they're
+fixed in our internal repositories first.</p>
+
+<p>The component is also a factor in how users get updates. A bug in the framework
+or kernel will require an over-the-air (OTA) firmware update that each OEM will
+need to push. A bug in an app or library published in Google Play (e.g., Gmail,
+Google Play Services, WebView in Lollipop and later versions) can be sent to
+Android users as an update from Google Play. </p>
+
+<h2 id=notifying_partners>Notifying partners</h2>
+
+<p>When a moderate or higher severity security vulnerability in AOSP is fixed,
+we'll notify <a href="http://www.openhandsetalliance.com/">Open Handset
+Alliance</a> members with the details of the issue and provide patches for the
+most recent three Android releases. The Android security team currently
+provides patches for Android versions 4.4 (KitKat), 5.0 (Lollipop), and 5.1
+(Lollipop MR1). This list of backport-supported versions changes with each new
+Android release.</p>
+
+<h2 id=releasing_code_to_aosp>Releasing code to AOSP</h2>
+
+<p>If the security bug is in an AOSP component, the fix will be pushed out to AOSP
+after the OTA is released to users. Fixes for low-severity issues may be
+submitted directly to the AOSP master branch before a fix is available.</p>
+
+<h2 id=android_updates>Receiving Android updates</h2>
+
+<p>Updates to the Android system are generally delivered to devices through
+OTA update packages. These updates may come from the OEM who
+produced the device or the carrier who provides service to the device. Google
+Nexus device updates come from the Google Nexus team after going through a
+carrier technical acceptance (TA) testing procedure. Google also publishes <a
+href="https://developers.google.com/android/nexus/images">Nexus factory
+images</a> that can be side-loaded to devices.</p>
+
+<h2 id=updating_google_services>Updating Google services</h2>
+
+<p>In addition to providing patches for security bugs, the Android security team
+also review security bugs to determine if there are other ways to protect
+users. For example, Google Play scans all applications and will remove any
+application that attempts to exploit a security bug. For applications installed
+from outside of Google Play, devices with Google Play Services may also use the
+<a href="https://support.google.com/accounts/answer/2812853">Verify Apps</a>
+feature to warn users about applications that may be potentially harmful.</p>
+
+<h2 id=other_resources>Other resources</h2>
+
+<p>Information for Android application developers: <a
+href="https://developer.android.com">https://developer.android.com</a></p>
+
+<p>The Android security team can be reached at <a
+href="mailto:security@android.com">security@android.com</a>. Our PGP key: <a
+href="https://developer.android.com/security_at_android_dot_com.txt">https://developer.android.com/security_at_android_dot_com.txt</a></p>
+
+<p>Security information exists throughout the Android Open Source and Developer
+sites. Good places to start:<br>
+<a href="http://source.android.com/security/index.html">{@docRoot}security/index.html</a><br>
+<a href="https://developer.android.com/training/articles/security-tips.html">https://developer.android.com/training/articles/security-tips.html</a></p>
+
+<p>Community resource for discussion about Android security: <a
+href="https://groups.google.com/forum/?fromgroups#!forum/android-security-discuss">https://groups.google.com/forum/?fromgroups#!forum/android-security-discuss</a></p>
diff --git a/src/security/security_toc.cs b/src/security/security_toc.cs
new file mode 100644
index 0000000..467e35d
--- /dev/null
+++ b/src/security/security_toc.cs
@@ -0,0 +1,113 @@
+<!--
+ Copyright 2015 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.
+-->
+<?cs # Table of contents for security?>
+<ul id="nav">
+ <!-- Security -->
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/index.html">
+ <span class="en">Security</span>
+ </a>
+ </div>
+ <ul>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/overview/index.html">
+ <span class="en">Overview</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>security/overview/kernel-security.html">Kernel security</a></li>
+ <li><a href="<?cs var:toroot ?>security/overview/app-security.html">App security</a></li>
+ <li><a href="<?cs var:toroot ?>security/overview/updates-resources.html">Updates and resources</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/enhancements/index.html">
+ <span class="en">Enhancements</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>security/enhancements/enhancements60.html">Android 6.0</a></li>
+ <li><a href="<?cs var:toroot ?>security/enhancements/enhancements50.html">Android 5.0</a></li>
+ <li><a href="<?cs var:toroot ?>security/enhancements/enhancements44.html">Android 4.4</a></li>
+ <li><a href="<?cs var:toroot ?>security/enhancements/enhancements43.html">Android 4.3</a></li>
+ <li><a href="<?cs var:toroot ?>security/enhancements/enhancements42.html">Android 4.2</a></li>
+ <li><a href="<?cs var:toroot ?>security/enhancements/enhancements41.html">Android 4.1</a></li>
+ </ul>
+ </li>
+ <li><a href="<?cs var:toroot ?>security/overview/acknowledgements.html">Acknowledgements</a></li>
+ </ul>
+ </li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/implement.html">
+ <span class="en">Implementation</span>
+ </a>
+ </div>
+ <ul>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/authentication/index.html">
+ <span class="en">Authentication</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>security/authentication/fingerprint-hal.html">Fingerprint HAL</a></li>
+ <li><a href="<?cs var:toroot ?>security/authentication/gatekeeper.html">Gatekeeper</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/authentication/keymaster.html">
+ <span class="en">Keymaster</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>security/authentication/km-features.html">Features</a></li>
+ <li><a href="<?cs var:toroot ?>security/authentication/km-implementer-ref.html">Implementer's Reference</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><a href="<?cs var:toroot ?>security/encryption/index.html">Full Disk Encryption</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/selinux/index.html">
+ <span class="en">SELinux</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>security/selinux/concepts.html">Concepts</a></li>
+ <li><a href="<?cs var:toroot ?>security/selinux/implement.html">Implementation</a></li>
+ <li><a href="<?cs var:toroot ?>security/selinux/customize.html">Customization</a></li>
+ <li><a href="<?cs var:toroot ?>security/selinux/validate.html">Validation</a></li>
+ </ul>
+ </li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>security/verifiedboot/index.html">
+ <span class="en">Verified Boot</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>security/verifiedboot/verified-boot.html">Verifying boot</a></li>
+ <li><a href="<?cs var:toroot ?>security/verifiedboot/dm-verity.html">Implementing dm-verity</a></li>
+ </ul>
+ </li>
+
+ </ul>
+ </li>
+ </ul>
+ <!-- End Security -->
+</ul>
diff --git a/src/security/selinux/concepts.jd b/src/security/selinux/concepts.jd
new file mode 100644
index 0000000..1958474
--- /dev/null
+++ b/src/security/selinux/concepts.jd
@@ -0,0 +1,174 @@
+page.title=SELinux concepts
+@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>
+
+<p>Review this page to become familar with the concepts at play within SELinux.</p>
+
+<h2 id=mandatory_access_control>Mandatory access control</h2>
+
+<p>Security Enhanced Linux (SELinux), is a mandatory access control (MAC) system
+for the Linux operating system. As a MAC system, it differs from Linux’s
+familiar discretionary access control (DAC) system. In a DAC system, a concept
+of ownership exists, whereby an owner of a particular resource controls access
+permissions associated with it. This is generally coarse-grained and subject
+to unintended privilege escalation. A MAC system, however, consults a central
+authority for a decision on all access attempts.</p>
+
+<p>SELinux has been implemented as part of the Linux Security Module (LSM)
+framework, which recognizes various kernel objects, and sensitive actions
+performed on them. At the point at which each of these actions would be
+performed, an LSM hook function is called to determine whether or not the
+action should be allowed based on the information for it stored in an opaque
+security object. SELinux provides an implementation for these hooks and
+management of these security objects, which combine with its own policy, to
+determine the access decisions.</p>
+
+<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 process assigned the root
+privilege can write to only those specified in the associated policy. In this
+way, the process cannot overwrite data and system settings outside of the
+specific raw block device.</p>
+
+<p>See <a href="implement.html#use_cases">Use Cases</a> for more examples of threats and ways to address them with SELinux.</p>
+
+<h2 id=enforcement_levels>Enforcement levels</h2>
+
+<p>Become familiar with the following terms to understand how SELinux can be
+implemented to varying strengths.</p>
+
+<ul>
+ <li><em>Permissive</em> - SELinux security policy is not enforced, only logged.
+ <li><em>Enforcing</em> - Security policy is enforced and logged. Failures appear as EPERM errors.
+</ul>
+
+<p>This choice is binary and determines whether your policy takes action or merely
+allows you to gather potential failures. Permissive is especially useful during
+implementation.</p>
+
+<ul>
+ <li><em>Unconfined</em> - A very light policy that prohibits certain tasks and provides a temporary
+stop-gap during development. Should not be used for anything outside of the
+Android Open Source Project (AOSP).
+ <li><em>Confined</em> - A custom-written policy designed for the service. That policy should define
+precisely what is allowed.
+</ul>
+
+<p>Unconfined policies are available to help implement SELinux in Android quickly.
+They are suitable for most root-level applications. But they should be
+converted to confined policies wherever possible over time to restrict each
+application to precisely the resources it needs.</p>
+
+<p>Ideally, your policy is both in enforcing mode and confined. Unconfined
+policies in enforcement mode can mask potential violations that would have been
+logged in permissive mode with a confined policy. Therefore, we strongly
+recommend partners implement true confined policies.</p>
+
+<h2 id=labels_rules_and_domains>Labels, rules and domains</h2>
+
+<p>SELinux depends upon <em>labels</em> to match actions and policies. Labels determine what is allowed. Sockets,
+files, and processes all have labels in SELinux. SELinux decisions are based
+fundamentally on labels assigned to these objects and the policy defining how
+they may interact. In SELinux, a label takes the form:
+user:role:type:mls_level, where the type is the primary component of the access
+decisions, which may be modified by the other sections components which make up
+the label. The objects are mapped to classes and the different types of access
+for each class are represented by permissions. </p>
+
+<p>The policy rules come in the form: allow <em>domains</em> <em>types</em>:<em>classes</em> <em>permissions</em>;, where:</p>
+
+<ul>
+ <li><em>Domain</em> - A label for the process or set of processes. Also called a domain type as it is just a type for a process.
+ <li><em>Type</em> - A label for the object (e.g. file, socket) or set of objects.
+ <li><em>Class</em> - The kind of object (e.g. file, socket) being accessed.
+ <li><em>Permission</em> - The operation (e.g. read, write) being performed.
+</ul>
+
+<p>And so an example use of this would follow the structure:</p>
+<code>allow appdomain app_data_file:file rw_file_perms;</code>
+
+<p>This says that all application domains are allowed to read and write files labeled
+app_data_file. Note that this rule relies upon macros defined in the
+global_macros file, and other helpful macros can also be found in the te_macros
+file, both of which can be found in the <a href="https://android.googlesource.com/platform/external/sepolicy/">external/sepolicy</a> directory in the AOSP source tree. Macros are provided for common groupings of classes, permissions and
+rules, and should be used whenever possible to help reduce the likelihood of
+failures due to denials on related permissions.</p>
+
+<p>In addition to individually listing domains or types in a rule, one can also refer to a set of domains or types via an <em>attribute</em>. An attribute is simply a name for a set of domains or types. Each domain or type can be associated with any number of attributes. When a rule is written that specifies an attribute name, that name is automatically expanded to the list of domains or types associated with the attribute. For example, the <em>domain</em> attribute is associated with all process domains, and the <em>file_type</em> attribute is associated with all file types.</p>
+
+<p>Use the syntax above to create avc rules that comprise the essence of an
+SELinux policy. A rule takes the form:
+<pre>
+<rule variant> <source_types> <target_types> : <classes> <permissions>
+</pre>
+
+<p>The rule indicates what should happen when a subject labeled with any of the <em>source_types</em> attempts an action corresponding to any of the <em>permissions</em> on an object with any of the class <em>classes</em> which has any of the <em>target_types</em> label. The most common example of one of these rules is an allow rule, e.g.:</p>
+
+<pre>
+allow domain null_device:chr_file { open };
+</pre>
+
+
+<p>
+This rule allows a process with any <em>domain</em> associated with the ‘domain’ attribute to take the action described by the <em>permission</em> ‘open’ on an object of <em>class</em> ‘chr_file’ (character device file) that has the <em>target_type</em> label of ‘null_device.’ In practice, this rule may be extended to include other permissions: </p>
+
+<pre>
+allow domain null_device:chr_file { getattr open read ioctl lock append write};
+</pre>
+
+<p>When combined with the knowledge that ‘domain’ is an attribute assigned to
+all process domains and
+that null_device is the label for the character device /dev/null, this rule basically
+permits reading and writing to <code>/dev/null</code>.</p>
+
+<p>A <em>domain</em> generally corresponds to a process and will have a label associated with it.</p>
+
+<p>For example, a typical Android app is running in its own process and has the
+label of untrusted_app that grants it certain restricted permissions.</p>
+
+<p>Platform apps built into the system run under a separate label and are granted
+a distinct set of permissions. System UID apps that are part of the core Android
+system run under the system_app label for yet another set of privileges.</p>
+
+<p>Access to the following generic labels should never be directly allowed to domains; instead, a more specific type should be created for the object or objects:</p>
+
+<ul>
+ <li> socket_device
+ <li> device
+ <li> block_device
+ <li> default_service
+ <li> system_data_file
+ <li> tmpfs
+</ul>
diff --git a/src/security/selinux/customize.jd b/src/security/selinux/customize.jd
new file mode 100644
index 0000000..a84d60f
--- /dev/null
+++ b/src/security/selinux/customize.jd
@@ -0,0 +1,300 @@
+page.title=Customizing SELinux
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<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>When embarking upon customizing SELinux, manufacturers should remember to:</p>
+
+<ul>
+ <li>Write SELinux policy for all new daemons
+ <li>Use predefined domains whenever appropriate
+ <li>Assign a domain to any process spawned as an <code>init</code> service
+ <li>Become familiar with the macros before writing policy
+ <li>Submit changes to core policy to AOSP
+</ul>
+
+<p>And not to:</p>
+
+<ul>
+ <li>Create incompatible policy
+ <li>Allow end user policy customization
+ <li>Allow MDM policy customizations
+ <li>Scare users with policy violations
+ <li>Add backdoors
+</ul>
+
+<p>See the <em>Kernel Security Features</em> section of the <a href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition document</a> for specific requirements.</p>
+
+<p>SELinux uses a whitelist approach, meaning all access must be explicitly
+allowed in policy in order to be granted. 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>Use the <a href="https://android.googlesource.com/kernel/common/">latest Android kernel</a>.
+ <li>Adopt the <a href="http://en.wikipedia.org/wiki/Principle_of_least_privilege">principle of least privilege</a>.
+ <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>Compartmentalize software components into modules that conduct singular tasks.
+ <li>Create SELinux policies that isolate those tasks from unrelated functions.
+ <li>Put those policies in *.te files (the extension for SELinux policy source
+files) within the <code>/device/manufacturer/device-name/sepolicy</code> directory and use
+<code>BOARD_SEPOLICY</code> variables to include them in your build.
+ <li>Make new domains permissive initially. This is done by
+using a permissive declaration in the domain's .te file.
+ <li>Analyze results and refine your domain definitions.
+ <li>Remove the permissive declaration when no further denials appear in userdebug
+builds.
+</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 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 enforcing mode.</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>
+
+<h2 id=example_policy_statements>Example policy statements</h2>
+
+<p>First, note SELinux is based upon the <a href="https://www.gnu.org/software/m4/manual/index.html">M4</a> computer language and therefore supports a variety of macros to save time.</p>
+
+<p>In the following example, all domains are granted access to read from or write to <code>/dev/null</code> and read from <code>/dev/zero</code>.</p>
+
+<pre>
+# Allow read / write access to /dev/null
+allow domain null_device:chr_file { getattr open read ioctl lock append write};
+
+# Allow read-only access to /dev/zero
+allow domain zero_device:chr_file { getattr open read ioctl lock };
+</pre>
+
+
+<p>This same statement can be written with SELinux <code>*_file_perms</code> macros (shorthand):</p>
+
+<pre>
+# Allow read / write access to /dev/null
+allow domain null_device:chr_file rw_file_perms;
+
+# Allow read-only access to /dev/zero
+allow domain zero_device:chr_file r_file_perms;
+</pre>
+
+<h2 id=example_policy>Example policy</h2>
+
+<p>Here is a complete example policy for DHCP, which we examine below:</p>
+
+<pre>
+type dhcp, domain;
+permissive dhcp;
+type dhcp_exec, exec_type, file_type;
+type dhcp_data_file, file_type, data_file_type;
+
+init_daemon_domain(dhcp)
+net_domain(dhcp)
+
+allow dhcp self:capability { setgid setuid net_admin net_raw net_bind_service
+};
+allow dhcp self:packet_socket create_socket_perms;
+allow dhcp self:netlink_route_socket { create_socket_perms nlmsg_write };
+allow dhcp shell_exec:file rx_file_perms;
+allow dhcp system_file:file rx_file_perms;
+# For /proc/sys/net/ipv4/conf/*/promote_secondaries
+allow dhcp proc_net:file write;
+allow dhcp system_prop:property_service set ;
+unix_socket_connect(dhcp, property, init)
+
+type_transition dhcp system_data_file:{ dir file } dhcp_data_file;
+allow dhcp dhcp_data_file:dir create_dir_perms;
+allow dhcp dhcp_data_file:file create_file_perms;
+
+allow dhcp netd:fd use;
+allow dhcp netd:fifo_file rw_file_perms;
+allow dhcp netd:{ dgram_socket_class_set unix_stream_socket } { read write };
+allow dhcp netd:{ netlink_kobject_uevent_socket netlink_route_socket
+netlink_nflog_socket } { read write };
+</pre>
+
+<p>Let’s dissect the example:</p>
+
+<p>In the first line, the type declaration, the DHCP daemon inherits from the base
+security policy (<code>domain</code>). From the previous statement examples, we know DHCP can read from and write
+to <code>/dev/null.</code></p>
+
+<p>In the second line, DHCP is identified as a permissive domain.</p>
+
+<p>In the <code>init_daemon_domain(dhcp)</code> line, the policy states DHCP is spawned from <code>init</code> and is allowed to communicate with it.</p>
+
+<p>In the <code>net_domain(dhcp)</code> line, the policy allows DHCP to use common network functionality from the <code>net</code> domain such as reading and writing TCP packets, communicating over sockets, and conducting DNS requests.</p>
+
+<p>In the line <code>allow dhcp proc_net:file write;</code>, the policy states DHCP can write to specific files in <code>/proc</code>. This line demonstrates SELinux’s fine-grained file labeling. It uses the <code>proc_net</code> label to limit write access to only the files under <code>/proc/sys/net</code>.</p>
+
+<p>The final block of the example starting with <code>allow dhcp netd:fd use;</code> depicts how applications may be allowed to interact with one another. The
+policy says DHCP and netd may communicate with one another via file
+descriptors, FIFO files, datagram sockets, and UNIX stream sockets. DHCP may
+only read to and write from the datagram sockets and UNIX stream sockets and
+not create or open them.</p>
+
+<h2 id=available_controls>Available controls</h2>
+
+<table>
+ <tr>
+ <td>
+<p><strong>Class</strong></p>
+</td>
+ <td>
+<p><strong>Permission</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>file</p>
+</td>
+ <td>
+<pre>
+ioctl read write create getattr setattr lock relabelfrom relabelto append
+unlink link rename execute swapon quotaon mounton</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>directory</p>
+</td>
+ <td>
+<pre>
+add_name remove_name reparent search rmdir open audit_access execmod</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>socket</p>
+</td>
+ <td>
+<pre>
+ioctl read write create getattr setattr lock relabelfrom relabelto append bind
+connect listen accept getopt setopt shutdown recvfrom sendto recv_msg send_msg
+name_bind</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>filesystem</p>
+</td>
+ <td>
+<pre>
+mount remount unmount getattr relabelfrom relabelto transition associate
+quotamod quotaget</pre>
+ </td>
+ </tr>
+ <tr>
+ <td>
+<p>process</p>
+ </td>
+ <td>
+<pre>
+fork transition sigchld sigkill sigstop signull signal ptrace getsched setsched
+getsession getpgid setpgid getcap setcap share getattr setexec setfscreate
+noatsecure siginh setrlimit rlimitinh dyntransition setcurrent execmem
+execstack execheap setkeycreate setsockcreate</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>security</p>
+</td>
+ <td>
+<pre>
+compute_av compute_create compute_member check_context load_policy
+compute_relabel compute_user setenforce setbool setsecparam setcheckreqprot
+read_policy</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>capability</p>
+</td>
+ <td>
+<pre>
+chown dac_override dac_read_search fowner fsetid kill setgid setuid setpcap
+linux_immutable net_bind_service net_broadcast net_admin net_raw ipc_lock
+ipc_owner sys_module sys_rawio sys_chroot sys_ptrace sys_pacct sys_admin
+sys_boot sys_nice sys_resource sys_time sys_tty_config mknod lease audit_write
+audit_control setfcap</pre>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p><strong>MORE</strong></p>
+</td>
+ <td>
+<p><strong>AND MORE</strong></p>
+</td>
+ </tr>
+</table>
+
+<h2 id=neverallow>neverallow rules</h2>
+
+<p>SELinux <code>neverallow</code> rules prohibit behavior that should never occur.
+With <a href="{@docRoot}compatibility/index.html">compatibility</a> testing,
+SELinux <code>neverallow</code> rules are now enforced across partner devices.</p>
+
+<p>The following guidelines are intended to help manufacturers avoid errors
+related to <code>neverallow</code> rules during customization. The rule numbers
+used here correspond to Android 5.1 and are subject to change by release.</p>
+
+<p>Rule 48: <code>neverallow { domain -debuggerd -vold -dumpstate
+-system_server } self:capability sys_ptrace;</code><br>
+See the man page for <code>ptrace</code>. The <code>sys_ptrace</code>
+capability grants the ability to <code>ptrace</code> any process, which allows a great deal
+of control over other processes and should belong only to designated system
+components, outlined in the rule. The need for this capability often indicates
+the presence of something that is not meant for user-facing builds or
+functionality that isn’t needed. Remove the unnecessary component.</p>
+
+<p>Rule 76: <code>neverallow { domain -appdomain -dumpstate -shell -system_server -zygote } { file_type -system_file -exec_type }:file execute;</code><br>
+This rule is intended to prevent the execution of arbitrary code on the system.
+Specifically, it asserts that only code on <code>/system</code> gets executed,
+which allows security guarantees thanks to mechanisms such as verified boot.
+Often, the best solution when encountering a problem with this
+<code>neverallow</code> rule is to move the offending code to the
+<code>/system</code> partition.</p>
diff --git a/src/security/selinux/implement.jd b/src/security/selinux/implement.jd
new file mode 100644
index 0000000..0655e1d
--- /dev/null
+++ b/src/security/selinux/implement.jd
@@ -0,0 +1,234 @@
+page.title=Implementing SELinux
+@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>
+
+<p>SELinux is set up to default-deny, which means that every single access for
+which it has a hook in the kernel must be explicitly allowed by policy. This
+means a policy file is comprised of a large amount of information regarding
+rules, types, classes, permissions, and more. A full consideration of SELinux
+is out of the scope of this document, but an understanding of how to write
+policy rules is now essential when bringing up new Android devices. There is a
+great deal of information available regarding SELinux already. See <a
+href="{@docRoot}devices/tech/security/selinux/index.html#supporting_documentation">Supporting
+documentation</a> for suggested resources.</p>
+
+<h2 id=summary_of_steps>Summary of steps</h2>
+
+<p>Here is a brief summary of the steps needed to implement SELinux on your
+Android device:</p>
+
+<ol>
+ <li>Add SELinux support in the kernel and configuration.
+ <li>Grant each service (process or daemon) started from <code>init</code> its own domain.
+ <li>Identify these services by:
+ <ul>
+ <li>Reviewing the init.<device>.rc file and finding all services.
+ <li>Examining warnings of the form <em>init: Warning! Service name needs a SELinux domain defined; please fix!</em> in <code>dmesg</code> output.
+ <li>Checking <code>ps -Z | grep init</code> output to see which services are running in the init domain.
+ </ul>
+ <li>Label all new processes, drivers, sockets, etc.
+All objects need to be labeled
+properly to ensure they interact properly with the policies you apply. See the
+labels used in AOSP for examples to follow in label name creation.
+ <li>Institute security policies that fully cover all labels and restrict
+permissions to their absolute minimum.
+</ol>
+
+<p>Ideally, OEMs start with the policies in the AOSP and then build upon them for
+their own customizations.</p>
+
+<h2 id=key_files>Key files</h2>
+
+<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/">external/sepolicy</a> directory:</p>
+
+<p><a href="https://android.googlesource.com/kernel/common/">https://android.googlesource.com/kernel/common/ </a></p>
+
+<p><a 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. You should not need to modify the
+external/sepolicy files directly. Instead, add your own device-specific policy
+files within the /device/manufacturer/device-name/sepolicy directory.</p>
+
+<p>Here are the files you must create or edit in order to implement SELinux:</p>
+
+<ul>
+ <li><em>New SELinux policy source (*.te) files</em> - Located in the
+<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 class="caution"><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><em>Updated BoardConfig.mk makefile</em> - Located in the <device-name>
+directory containing the sepolicy subdirectory. It must be updated to reference
+the sepolicy subdirectory once created if it
+wasn’t in initial implementation.
+ <li><em>file_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to files and is used by various userspace components. As you
+create new policies, create or update this file to
+assign new labels to files. In order to apply new file_contexts, you must
+rebuild the filesystem image or run <code>restorecon</code> on the file to be
+relabeled. On upgrades, changes to file_contexts are automatically applied to
+the system and userdata partitions as part of the upgrade. Changes can also be
+automatically applied on upgrade to other partitions by adding
+restorecon_recursive calls to your init.<em>board</em>.rc file after the
+partition has been mounted read-write.
+ <li><em>genfs_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to filesystems such as proc or vfat that do not support extended
+attributes. This configuration is loaded as part of the kernel policy but
+changes may not take effect for in-core inodes, requiring a reboot or
+unmounting and re-mounting the filesystem to fully apply the change. Specific
+labels may also be assigned to specific mounts such as vfat using the context=
+mount option.
+ <li><em>property_contexts</em> - Located in the sepolicy subdirectory. This
+file assigns labels to Android system properties to control what processes can
+set them. This configuration is read by the init process during startup and
+whenever the selinux.reload_policy property is set to 1.
+ <li><em>service_contexts</em> - Located in the sepolicy subdirectory. This
+file assigns labels to Android binder services to control what processes can
+add (register) and find (lookup) a binder reference for the service. This
+configuration is read by the servicemanager process during startup and whenever
+the selinux.reload_policy property is set to 1.
+ <li><em>seapp_contexts</em> - Located in the sepolicy subdirectory. This file
+assigns labels to app processes and /data/data directories. This configuration
+is read by the zygote process on each app launch and by installd during startup
+and whenever the selinux.reload_policy property is set to 1.
+ <li><em>mac_permissions.xml</em> - Located in the sepolicy subdirectory. This
+file assigns a seinfo tag to apps based on their signature and optionally their
+package name. The seinfo tag can then be used as a key in the seapp_contexts
+file to assign a specific label to all apps with that seinfo tag. This
+configuration is read by system_server during startup.
+</ul>
+
+<p>Then just update your BoardConfig.mk makefile - located in the directory
+containing the sepolicy subdirectory - to reference the sepolicy subdirectory
+and each policy file once created, as shown below. The BOARD_SEPOLICY variables
+and their meaning is documented in the external/sepolicy/README file.</p>
+
+<pre>
+BOARD_SEPOLICY_DIRS += \
+ <root>/device/manufacturer/device-name/sepolicy
+
+BOARD_SEPOLICY_UNION += \
+ genfs_contexts \
+ file_contexts \
+ sepolicy.te
+</pre>
+
+<p class="note"><strong>Note:</strong> As of the M release,
+BOARD_SEPOLICY_UNION is no longer required as all policy files found within any
+directory included in the BOARD_SEPOLICY_DIRS variable are joined with the
+base policy automatically.</p>
+
+<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 <a
+href="customize.html">Customization</a> or verify your existing setup as
+covered in <a href="validate.html">Validation</a>.</p>
+
+<p>Once the new policy files and BoardConfig.mk updates are in place, the new
+policy settings are automatically built into the final kernel policy file.</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 open.</p>
+
+<p>Attackers might then replace those files with symlinks to code they control,
+allowing the attacker to overwrite arbitrary files. But if you know your
+application will never traverse a symlink, you can prohibit it from doing so
+with SELinux.</p>
+
+<p><strong>System files</strong> - Consider the class of system files that should only be modified by the
+system server. Still, since netd, init, and vold run as root, they can access
+those system files. So if netd became compromised, it could compromise those
+files and potentially the system server itself.</p>
+
+<p>With SELinux, you can identify those files as system server data files.
+Therefore, the only domain that has read/write access to them is system server.
+Even if netd became compromised, it could not switch domains to the system
+server domain and access those system files although it runs as root.</p>
+
+<p><strong>App data</strong> - Another example is the class of functions that must run as root but should
+not get to access app data. This is incredibly useful as wide-ranging
+assertions can be made, such as certain domains unrelated to application data
+being prohibited from accessing the internet.</p>
+
+<p><strong>setattr</strong> - For commands such as chmod and chown, you could identify the set of files
+where the associated domain can conduct setattr. Anything outside of that could
+be prohibited from these changes, even by root. So an application might run
+chmod and chown against those labeled app_data_files but not shell_data_files
+or system_data_files.</p>
+
+<h2 id=steps_in_detail>Steps in detail</h2>
+
+<p>Here is a detailed view of how Android recommends you employ and customize
+SELinux to protect your devices:</p>
+
+<ol>
+ <li>Enable SELinux in the kernel:
+<code>CONFIG_SECURITY_SELINUX=y</code>
+ <li>Change the kernel_cmdline parameter so that:<br/>
+<code>BOARD_KERNEL_CMDLINE := androidboot.selinux=permissive</code>.
+<br/>
+This is only for initial development of policy for the device. Once you have
+an initial bootstrap policy, remove this parameter so that your device is
+enforcing or it will fail CTS.
+ <li>Boot up the system in permissive and see what denials are encountered on boot:<br/>
+On Ubuntu 14.04 or newer:
+<br/>
+<code>adb shell su -c dmesg | grep denied | audit2allow -p out/target/product/<em>board</em>/root/sepolicy</code>
+<br/>
+On Ubuntu 12.04:
+<code>adb shell su -c dmesg | grep denied | audit2allow</code>
+ <li>Evaluate the output. See <a href="validate.html">Validation</a> for instructions and tools.
+ <li>Identify devices, and other new files that need labeling.
+ <li>Use existing or new labels for your objects.
+Look at the *_contexts files to
+see how things were previously labeled and use knowledge of the label meanings
+to assign a new one. Ideally, this will be an existing label which will fit
+into policy, but sometimes a new label will be needed, and rules for access to
+that label will be needed, as well.
+ <li>Identify domains/processes that should have their own security domains. A policy will likely need to be written for each of these from scratch. All services spawned from <code>init</code>, for instance, should have their own. The following commands help reveal those that remain running (but ALL services need such a treatment):<br/>
+<code>$ adb shell su -c ps -Z | grep init</code><br/>
+<code>$ adb shell su -c dmesg | grep 'avc: '</code>
+ <li>Review init.<device>.rc to identify any which are without a type.
+These should
+be given domains EARLY in order to avoid adding rules to init or otherwise
+confusing <code>init</code> accesses with ones that are in their own policy.
+ <li>Set up <code>BOARD_CONFIG.mk</code> to use <code>BOARD_SEPOLICY_*</code> variables. See
+the README in external/sepolicy for details on setting this up.
+ <li> Examine the init.<device>.rc and fstab.<device> file and make sure every use of “mount”
+corresponds to a properly labeled filesystem or that a context= mount option is specified.
+ <li> Go through each denial and create SELinux policy to properly handle each. See
+the examples within <a href="customize.html">Customization</a>.
+</ol>
diff --git a/src/security/selinux/index.jd b/src/security/selinux/index.jd
new file mode 100644
index 0000000..3553bc7
--- /dev/null
+++ b/src/security/selinux/index.jd
@@ -0,0 +1,105 @@
+page.title=Security-Enhanced Linux in Android
+@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>The Android security model is based in part on the concept of application
+sandboxes. Each application runs in its own sandbox. Prior to Android 4.3,
+these sandboxes were defined by the creation of a unique Linux UID for each
+application at time of installation. Starting with Android 4.3,
+Security-Enhanced Linux (SELinux) is used to further define the boundaries of
+the Android application sandbox.</p>
+
+<p>As part of the Android <a href="{@docRoot}devices/tech/security/index.html">security model</a>, Android uses SELinux to enforce mandatory access control (MAC) over all
+processes, even processes running with root/superuser privileges (a.k.a. Linux
+capabilities). SELinux enhances Android security by confining privileged
+processes and automating security policy creation.</p>
+
+<p>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 protect and confine system services, 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 attempted
+violations are logged by the kernel to <code>dmesg</code> and <code>logcat</code>. Android device manufacturers should gather information about errors so they
+may refine their software and SELinux policies before enforcing them.</p>
+
+<h2 id=background>Background</h2>
+
+<p>SELinux operates on the ethos of default denial. Anything that is not
+explicitly allowed is denied. SELinux can operate in one of two global modes:
+permissive mode, in which permission denials are logged but not enforced, and
+enforcing mode, in which denials are both logged and enforced. SELinux also
+supports a per-domain permissive mode in which specific domains (processes) can
+be made permissive while placing the rest of the system in global enforcing
+mode. A domain is simply a label identifying a process or set of processes in
+the security policy, where all processes labeled with the same domain are
+treated identically by the security policy. Per-domain permissive mode enables
+incremental application of SELinux to an ever-increasing portion of the system.
+Per-domain permissive mode also enables policy development for new services
+while keeping the rest of the system enforcing.</p>
+
+<p>In the Android 5.0 (L) release, Android moves to full enforcement of SELinux. This builds
+upon the permissive release of 4.3 and the partial enforcement of 4.4. In
+short, Android is shifting from enforcement on a limited set of crucial domains
+(<code>installd</code>, <code>netd</code>, <code>vold</code> and <code>zygote</code>) to everything (more than 60 domains). This means manufacturers will have to
+better understand and scale their SELinux implementations to provide compatible
+devices. Understand that:</p>
+
+<ul>
+ <li> Everything is in enforcing mode in the 5.0 release
+ <li> No processes other than <code>init</code> should run in the <code>init</code> domain
+ <li> Any generic denial (for a block_device, socket_device, default_service, etc.)
+indicates that device needs a special domain
+</ul>
+
+<h2 id=supporting_documentation>Supporting documentation</h2>
+
+<p>See the documentation below for details on constructing useful policies:</p>
+
+<p><a href="http://seandroid.bitbucket.org/PapersandPresentations.html">http://seandroid.bitbucket.org/PapersandPresentations.html</a></p>
+
+<p><a href="https://www.codeproject.com/Articles/806904/Android-Security-Customization-with-SEAndroid">https://www.codeproject.com/Articles/806904/Android-Security-Customization-with-SEAndroid</a></p>
+
+<p><a href="https://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf">https://events.linuxfoundation.org/sites/events/files/slides/abs2014_seforandroid_smalley.pdf</a></p>
+
+<p><a href="https://www.internetsociety.org/sites/default/files/02_4.pdf">https://www.internetsociety.org/sites/default/files/02_4.pdf</a></p>
+
+<p><a href="http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf">http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf</a></p>
+
+<p><a href="http://selinuxproject.org/page/ObjectClassesPerms">http://selinuxproject.org/page/ObjectClassesPerms</a></p>
+
+<p><a href="https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf">https://www.nsa.gov/research/_files/publications/implementing_selinux.pdf</a></p>
+
+<p><a href="https://www.nsa.gov/research/_files/publications/selinux_configuring_policy.pdf">https://www.nsa.gov/research/_files/publications/selinux_configuring_policy.pdf</a></p>
+
+<p><a href="https://www.gnu.org/software/m4/manual/index.html">https://www.gnu.org/software/m4/manual/index.html</a></p>
+
+<h2 id=help>Help</h2>
+
+<p>Over time, Android intends to support common manufacturer additions in its
+default SELinux policy. For more information, contact <a href="mailto:security@android.com">security@android.com</a>.</p>
diff --git a/src/security/selinux/validate.jd b/src/security/selinux/validate.jd
new file mode 100644
index 0000000..34199f5
--- /dev/null
+++ b/src/security/selinux/validate.jd
@@ -0,0 +1,152 @@
+page.title=Validating SELinux
+@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>
+
+<p>Android strongly encourages OEMs to test their SELinux implementations
+thoroughly. As manufacturers implement SELinux, they should 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:getenforce</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 or run the latest version of <code>sepolicy-analyze</code> with the appropriate (-p) flag, present in /platform/external/sepolicy/tools/.</p>
+
+<h2 id=reading_denials>Reading denials</h2>
+
+<p>Then check for errors. Errors are routed as event logs to dmesg and <code>logcat</code> and are viewable locally on the device. Manufacturers should examine the
+SELinux output to dmesg on these devices and refine settings prior to public
+release in permissive mode and eventual switch to enforcing mode. SELinux log
+messages contain "avc:" and so may easily be found with <code>grep</code>. It is
+possible to capture the ongoing denial logs by running <code>cat /proc/kmsg</code>
+or to capture denial logs from the previous boot by running cat <code>/proc/last_kmsg</code>.</p>
+
+<p>With this output, manufacturers can readily identify when system users or
+components are in violation of SELinux policy. Manufacturers can then repair
+this bad behavior, either by changes to the software, SELinux policy, or both.</p>
+
+<p>Specifically, these log messages indicate what processes would fail under
+enforcing mode and why. Here is an example:</p>
+
+<pre>
+avc: 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 <code>{ connectto }</code> above represents the action being taken. Together with the
+<code>tclass</code> at the end (<code>unix_stream_socket</code>), it tells you roughly what was being done
+to what. In this case, something was trying to connect to a unix stream socket.
+ <li> The <code>scontext (u:r:shell:s0)</code> tells you what context initiated the action. In
+this case this is something running as the shell.
+ <li> The <code>tcontext (u:r:netd:s0)</code> tells you the context of the action’s target. In
+this case, that’s a unix_stream_socket owned by <code>netd</code>.
+ <li> The <code>comm="ping"</code> 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.
+</ul>
+
+<p>And here is another example:</p>
+
+<pre>
+$ adb shell su -c dmesg | grep 'avc: '
+<5> type=1400 audit: avc: denied { read write } for pid=177
+comm="rmt_storage" name="mem" dev="tmpfs" ino=6004 scontext=u:r:rmt:s0
+tcontext=u:object_r:kmem_device:s0 tclass=chr_file
+</pre>
+
+
+<p>Here are the key elements from this denial:</p>
+
+<ul>
+ <li><em>Action</em> - the attempted action is highlighted in brackets, <code>read write</code> or <code>setenforce</code>.
+ <li><em>Actor</em> - The <code>scontext</code> (source context) entry represents the actor, in this case the<code> rmt_storage</code> daemon.
+ <li><em>Object</em> - The <code>tcontext</code> (target context) entry represents the object being acted upon, in this case
+kmem.
+ <li><em>Result</em> - The <code>tclass</code> (target class) entry indicates the type of object being acted upon, in this
+case a <code>chr_file</code> (character device).
+</ul>
+
+<h2 id=switching_to_permissive>Switching to permissive</h2>
+
+<p class="caution"><strong>Important:</strong> Permissive mode is not supported on production devices. CTS tests confirm
+enforcing mode is enabled.</p>
+
+<p>To turn a device’s SELinux enforcement into globally permissive via ADB, as
+root issue:</p>
+
+<pre>
+$ adb shell su -c setenforce 0
+</pre>
+
+<p>Or at the kernel command line (during early device bring-up):</p>
+
+<pre>
+androidboot.selinux=permissive
+androidboot.selinux=disabled
+androidboot.selinux=enforcing
+</pre>
+
+<h2 id=using_audit2allow>Using audit2allow</h2>
+
+<p>The <code>selinux/policycoreutils/audit2allow</code> tool takes <code>dmesg</code> denials and converts them into corresponding SELinux policy statements. As
+such, it can greatly speed SELinux development. To install it, run:</p>
+
+<pre>
+$ sudo apt-get install policycoreutils
+</pre>
+
+<p>To use it on Ubuntu 12.04, run:</p>
+
+<pre>
+$ adb shell su -c dmesg | audit2allow
+</pre>
+
+<p>On Ubuntu 14.04 and newer, audit2allow requires you to specify the Android policy
+using the -p option, e.g.
+<pre>
+$ adb shell su -c dmesg | audit2allow -p out/target/product/<device>/root/sepolicy
+</pre>
+
+<p>Nevertheless, care must be taken to examine each potential addition for
+overreaching permissions. For example, feeding audit2allow the <code>rmt_storage</code> denial shown earlier results in the following suggested SELinux policy
+statement:</p>
+
+<pre>
+#============= shell ==============
+allow shell kernel:security setenforce;
+#============= rmt ==============
+allow rmt kmem_device:chr_file { read write };
+</pre>
+
+
+<p>This would grant <code>rmt</code> the ability to write kernel memory, a glaring security hole. Often the <code>audit2allow</code> statements are only a starting point, after which changes to the source
+domain, the label of the target and the incorporation of proper macros may be
+required to arrive at a good policy. Sometimes the denial being examined should
+not result in any policy changes at all, but rather the offending application
+should be changed.</p>
diff --git a/src/security/verifiedboot/dm-verity.jd b/src/security/verifiedboot/dm-verity.jd
new file mode 100644
index 0000000..0b03dda
--- /dev/null
+++ b/src/security/verifiedboot/dm-verity.jd
@@ -0,0 +1,246 @@
+page.title=Implementing dm-verity
+@jd:body
+
+<!--
+ Copyright 2015 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="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 <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
+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="implementation">Implementation</h2>
+
+<h3 id="summary">Summary</h3>
+
+<ol>
+<li>Generate an ext4 system image.</li>
+<li><a href="#hash-tree">Generate a hash tree</a> for that image.</li>
+<li><a href="#mapping-table">Build a dm-verity table</a> for that hash tree.</li>
+<li><a href="#signing">Sign that dm-verity table</a> to produce a table
+signature.</li>
+<li><a href="#metadata">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="#introduction">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>
+
+<p class="table-caption" id="table1">
+ <strong>Table 1.</strong> Verity 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>
+
+<h3 id="optimize">Optimizing dm-verity</h3>
+
+<p>To get the best performance out of dm-verity, you should:</p>
+ <ul>
+ <li>In the kernel, turn on NEON SHA-2 for ARMv7 and the SHA-2 extensions for ARMv8.
+ <li>Experiment with different read-ahead and prefetch_cluster settings to find the best configuration for your device.
+ </ul>
diff --git a/src/security/verifiedboot/index.jd b/src/security/verifiedboot/index.jd
new file mode 100644
index 0000000..d254074
--- /dev/null
+++ b/src/security/verifiedboot/index.jd
@@ -0,0 +1,93 @@
+page.title=Verified Boot
+@jd:body
+
+<!--
+ Copyright 2015 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 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 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 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>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>
+
+<img src="../images/dm-verity-hash-table.png" alt="dm-verity-hash-table" id="figure1"/>
+<p class="img-caption">
+ <strong>Figure 1.</strong> dm-verity hash table
+</p>
+
+<p>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="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.html">Verified
+boot</a>.</p>
+
+<h3 id="block-otas">Switching to block-oriented OTAs</h3>
+<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="{@docRoot}devices/tech/ota/block.html">Block-Based OTAs</a>.</p>
+
+<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 <code>CONFIG_DM_VERITY</code>.</p>
+
+<p>When using the Android kernel, dm-verity is turned on when the kernel is
+built. For details, see <a href="dm-verity.html">Implementing dm-verity</a>.</p>
+
+<h2 id="supporting-docs">Supporting documentation</h2>
+<p><a href="verified-boot.html">Verifying Boot</a><br/>
+<a href="{@docRoot}devices/tech/ota/block.html">Block-Based OTA</a><br/>
+<a href="dm-verity.html">Implementing dm-verity</a><br/>
+<a href="https://gitlab.com/cryptsetup/cryptsetup/wikis/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>
+
+<p>For additional assistance, contact
+<a href="mailto:security@android.com">security@android.com</a>.</p>
\ No newline at end of file
diff --git a/src/security/verifiedboot/verified-boot.jd b/src/security/verifiedboot/verified-boot.jd
new file mode 100644
index 0000000..19a95a4
--- /dev/null
+++ b/src/security/verifiedboot/verified-boot.jd
@@ -0,0 +1,527 @@
+page.title=Verifying Boot
+@jd:body
+
+<!--
+ Copyright 2015 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=objective>Objective</h2>
+<p>Verified boot guarantees the integrity of the device software starting from a
+hardware root of trust up to the system partition. During boot, each stage
+verifies the integrity and authenticity of the next stage before executing it.</p>
+
+<p>This capability can be used to warn users of unexpected changes to the
+software when they acquire a used device, for example. It will also provide an
+additional signal of device integrity for remote attestation, and together with
+encryption and Trusted Execution Environment (TEE) root of trust binding, adds
+another layer of protection for user data against malicious system software.</p>
+
+<p>Note that if verification fails at any stage, the user must be visibly
+notified and always be given an option to continue using the device at
+their own discretion.</p>
+
+<h2 id=glossary>Glossary</h2>
+
+<p class="table-caption" id="table1">
+ <strong>Table 1.</strong> Glossary of terms related to verified boot</p>
+
+<table>
+ <tr>
+ <td>
+<p><strong>Term</strong></p>
+</td>
+ <td>
+<p><strong>Definition</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Boot state</p>
+</td>
+ <td>
+<p>The boot state of the device describes the level of protection provided to the
+end user if the device boots. Boot states are GREEN, YELLOW, ORANGE, and RED.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Device state</p>
+</td>
+ <td>
+<p>The device state indicates how freely software can be flashed to the device.
+Device states are LOCKED and UNLOCKED.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>dm-verity</p>
+</td>
+ <td>
+<p>Linux kernel driver for verifying the integrity of a partition at runtime using
+a hash tree and signed metadata.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>Keystore</p>
+</td>
+ <td>
+<p>A keystore is a signed collection of public keys.</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>OEM key</p>
+</td>
+ <td>
+<p>The OEM key is a fixed, tamper-protected key available to the bootloader that
+must be used to verify the boot image.</p>
+</td>
+ </tr>
+</table>
+
+<h2 id=overview>Overview</h2>
+
+<p>In addition to device state - which already exists in devices and controls
+whether the bootloader allows new software to be flashed - we introduce the
+concept of boot state that indicates the state of device integrity.</p>
+
+<h3 id=classes>Classes</h3>
+
+<p>We define two implementation classes for verified boot depending on how
+fully the device implements this specification, as follows:</p>
+
+<p><strong>Class A</strong> implements verified boot with full chain of trust
+up to verified partitions. This implementation must support the LOCKED device
+state, and GREEN and RED boot states.</p>
+
+<p><strong>Class B</strong> implements Class A and additionally supports the
+UNLOCKED device state and the ORANGE boot state.</p>
+
+<h3 id=verification_keys>Verification keys</h3>
+
+<p>Bootloader integrity must be verified using a hardware root of trust. For
+verifying boot and recovery partitions, the bootloader must have a fixed OEM key
+available to it. It must always attempt to verify the boot partition using the OEM
+key first and try other possible keys only if this verification fails.</p>
+
+<p>In Class B implementations, it must be possible for the user to flash
+software signed with other keys when the device is UNLOCKED. If the device is
+then LOCKED and verification using the OEM key fails, the bootloader must try
+verification using the certificate embedded in the partition signature.
+However, using a partition signed with anything other than the OEM key must
+result in a notification or a warning, as described below.</p>
+
+<h3 id=boot_state>Boot state</h3>
+
+<p>A verified device will ultimately boot into one of four states during each boot
+attempt:</p>
+
+<ul>
+ <li>GREEN, indicating a full chain of trust extending from the bootloader to
+verified partitions, including the bootloader, boot partition, and all verified
+partitions.
+
+ <li>YELLOW, indicating the boot partition has been verified using the
+embedded certificate, and the signature is valid. The bootloader is required to
+display a notification and the fingerprint of the public key during boot.
+
+ <li>ORANGE, indicating a device may be freely modified. Device integrity is
+left to the user to verify out-of-band. The bootloader must display a warning
+to the user before allowing the boot process to continue.
+
+ <li>RED, indicating the device has failed verification. The bootloader must
+display a warning to the user before allowing the boot process to continue.
+</ul>
+
+<p>The recovery partition must also be verified in the exact same way.</p>
+
+<h3 id=device_state>Device state</h3>
+
+<p>The device is required to be in one of two states at all times:</p>
+
+<ol>
+ <li>LOCKED, indicating the device cannot be flashed. A LOCKED device must
+boot into the GREEN, YELLOW, or RED states during any attempted boot.
+
+ <li>UNLOCKED, indicating the device may be flashed freely and is not intended
+to be verified. An UNLOCKED device must always boot to the ORANGE boot state.
+</ol>
+
+<img src="../images/verified_boot.png" alt="Verified boot flow" id="figure1" />
+<p class="img-caption"><strong>Figure 1.</strong> Verified boot flow</p>
+
+<h2 id=detailed_design>Detailed design</h2>
+
+<p>Achieving full chain of trust requires support from both the bootloader and the
+software on the boot partition, which is responsible for mounting further
+partitions. Verification metadata must also be appended to the system partition
+and any additional partitions whose integrity should be verified.</p>
+
+<h3 id=bootloader_requirements>Bootloader requirements</h3>
+
+<p>The bootloader is the guardian of the device state and is responsible for
+initializing the TEE and binding its root of trust.</p>
+
+<p>Most importantly, the bootloader must verify the integrity of the boot and/or
+recovery partition before moving execution to the kernel and display the
+warnings specified in the section <a href="#boot_state">Boot state</a>.</p>
+
+<h4 id=changing_device_state>Changing device state</h4>
+
+<p>State changes are performed using the <code>fastboot flashing [unlock |
+lock]</code> command. And to protect user data, <strong>all</strong>
+state transitions require a data wipe. Note the user must be asked for
+confirmation before data is deleted.</p>
+
+<ol>
+ <li>The UNLOCKED to LOCKED transition is anticipated when a user buys a used
+development device. As a result of locking the device, the user should have
+confidence that it is in a state produced by the OEM.
+
+ <li>The LOCKED to UNLOCKED transition is expected in the case where a developer
+wishes to disable verification on the device.
+</ol>
+
+<p>Requirements for <code>fastboot</code> commands that alter device state are listed in the table below:</p>
+
+<p class="table-caption" id="table2">
+ <strong>Table 2.</strong> <code>fastboot</code> commands</p>
+
+<table>
+ <tr>
+ <td>
+<p><strong><code>fastboot</code> command</strong></p>
+</td>
+ <td>
+<p><strong>Requirements</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flashing lock</code></td>
+ <td>
+<ul>
+ <li>Wipe data after asking the user for confirmation
+ <li>Clear a write-protected bit indicating the device is unlocked
+</ul>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flashing unlock</code></td>
+ <td>
+<ul>
+ <li>Wipe data after asking the user for confirmation
+ <li>Set a write-protected bit indicating the device is unlocked
+</ul>
+</td>
+ </tr>
+</table>
+
+<p>When altering partition contents, the bootloader must check the bits set by
+the above commands as described in the following table:</p>
+
+<p class="table-caption" id="table3">
+ <strong>Table 3.</strong> <code>fastboot</code> command requirements</p>
+
+<table>
+ <tr>
+ <td>
+<p><strong><code>fastboot</code> command</strong></p>
+</td>
+ <td>
+<p><strong>Requirements</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<code>
+flash <partition></code></td>
+ <td>
+ <p>If the bit set by <code>flashing unlock</code> is set, flash the
+ partition. Otherwise, do not allow flashing.<p>
+ </td>
+ </tr>
+</table>
+
+<p>The same checks should be performed for any <code>fastboot</code> command
+that can be used to change the contents of partitions.</p>
+
+<p class="note"><strong>Note</strong>: Class B implementations must support
+changing device state.</p>
+
+<h4 id=binding_tee_root_of_trust>Binding TEE root of trust</h4>
+
+<p>If TEE is available, the bootloader should pass the following information to
+the TEE to bind the Keymaster root of trust, after partition verification and
+TEE initialization:</p>
+
+<ol>
+ <li>the public key that was used to sign the boot partition
+ <li>the current device state (LOCKED or UNLOCKED)
+</ol>
+
+<p>This changes the keys derived by the TEE. Taking disk encryption as an example,
+this prevents user data from being decrypted when the device state changes.</p>
+
+<p class="note"><strong>Note:</strong> This means if the system software or the
+device state changes, encrypted user data will no longer be accessible as the
+TEE will attempt to use a different key to decrypt the data.</p>
+
+<h4 id=booting_into_recovery>Booting into recovery</h4>
+
+<p>The recovery partition should be verified in exactly the same manner as the
+boot partition.</p>
+
+<h4 id=comm_boot_state>Communicating boot state</h4>
+
+<p>System software needs to be able to determine the verification status of
+previous stages. The bootloader must specify the current boot state as a
+parameter on the kernel command line (or through the device tree under
+<code>firmware/android/verifiedbootstate</code>) as described in the table
+below:</p>
+
+<p class="table-caption" id="table4">
+ <strong>Table 4.</strong> Kernel command line parameters</p>
+
+<table>
+ <tr>
+ <th>Kernel command line parameter</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td><code>androidboot.verifiedbootstate=green</code></td>
+ <td>Device has booted into GREEN boot state.<br>
+ Boot partition has been verified using the OEM key and it’s valid.</td>
+ </tr>
+ <tr>
+ <td><code>androidboot.verifiedbootstate=yellow</code></td>
+ <td>Device has booted into YELLOW boot state.<br>
+ Boot partition has been verified using the certificate embedded into
+ the signature and it’s valid.</td>
+ </tr>
+ <tr>
+ <td><code>androidboot.verifiedbootstate=orange</code></td>
+ <td>Device has booted into ORANGE boot state.<br>
+ The device is unlocked and no verification has been performed.</td>
+ </tr>
+ <tr>
+ <td><code>androidboot.verifiedbootstate=red</code></td>
+ <td>Device has booted into RED boot state.<br>
+ The device has failed verification.</td>
+ </tr>
+</table>
+
+<h3 id=boot_partition>Boot partition</h3>
+
+<p>Once execution has moved to the boot partition, the software there is responsible
+for setting up verification of further partitions. Due to its large size, the
+system partition typically cannot be verified similarly to previous parts but must be
+verified as it’s being accessed instead using the dm-verity kernel driver or a
+similar solution.</p>
+
+<p>If dm-verity is used to verify large partitions, the signature of the verity
+metadata appended to each verified partition must be verified before the
+partition is mounted and dm-verity is set up for it.</p>
+
+<h4 id=managing_dm-verity>Managing dm-verity</h4>
+
+<p>By default, dm-verity operates in enforcing mode and verifies each block read
+from the partition against a hash tree passed to it during setup. If it
+comes across a block that fails to verify, it returns an I/O error and makes
+the block with unexpected contents inaccessible to user space. Depending on
+which block is corrupted, this may cause some of the programs that reside on
+the partition to malfunction.</p>
+
+<p>Using an optional verity table parameter, dm-verity can be configured to
+function in logging mode. If dm-verity is not started in enforcing mode for any
+reason, or verity metadata cannot be verified, a warning must be displayed to
+the user, similar to the one shown before booting into the RED state.</p>
+
+<img src="../images/dm-verity_mgmt.png" alt="dm-verity management" id="figure2" />
+<p class="img-caption"><strong>Figure 2.</strong> dm-verity management</p>
+
+<h4 id=recovering_from_dm-verity_errors>Recovering from dm-verity errors</h4>
+
+<p>Since the system partition is by far larger than the boot partition, the
+probability of verification errors is also higher. Specifically, there is a
+larger probability of unintentional disk corruption, which will cause a
+verification failure and can potentially make an otherwise functional device
+unusable if a critical block in the partition can no longer be accessed.</p>
+
+<p>It’s generally not possible to distinguish disk corruption from malicious
+changes, so any change to the system partition must result in the user being
+notified; and no unverified data must leak to user space until a warning has
+been shown. However, we must also assume most verification failures are
+not the result of malicious behavior; so the user must also have an option to
+continue using the device without verification.</p>
+
+<p>When a dm-verity error is detected, the device must be rebooted and
+dm-verity must be started in logging mode during all subsequent restarts until
+any of the verified partitions is reflashed or changed by an OTA update. This
+means dm-verity state should be stored in a persistent flag. When a verified
+partition has been changed, the flag must be cleared and dm-verity must again
+be started in enforcing mode. Anytime dm-verity is not started in enforcing
+mode, a warning must be shown to the user before any of the verified partitions
+are mounted.</p>
+
+<h3 id=verified_partition>Verified partition</h3>
+
+<p>In a verified device, the system partition must always be verified. But any
+other read-only partition should also be set to be verified, as well. Any
+read-only partition that contains executable code must be verified on a
+verified device. This includes vendor and OEM partitions, if they exist, for example.</p>
+
+<p>In order for a partition to be verified, signed verity metadata must be
+appended to it. The metadata consists of a hash tree of the partition contents
+and a verity table containing signed parameters and the root of the hash tree.
+If this information is missing or invalid when dm-verity is set up for the
+partition, the user must be warned.</p>
+
+<h2 id=implementation_details>Implementation details</h2>
+
+<h3 id=key_types_and_sizes>Key types and sizes</h3>
+
+<p>The OEM key is recommended to be an RSA key with a modulus of 2048 bits or
+higher and a public exponent of 65537 (F4). The OEM key is required to be of
+equivalent or greater strength than such a key.</p>
+
+<h3 id=signature_format>Signature format</h3>
+
+<p>The signature on an Android verifiable boot image is an ASN.1 DER-encoded
+message, which can be parsed with a decoder similar to the one found at: <a
+href="https://android.googlesource.com/platform/bootable/recovery/+/f4a6ab27b335b69fbc419a9c1ef263004b561265/asn1_decoder.cpp">platform/bootable/recovery/asn1_decoder.cpp</a><br/>
+The message format itself is as follows:</p>
+
+<pre>
+AndroidVerifiedBootSignature DEFINITIONS ::=
+ BEGIN
+ FormatVersion ::= INTEGER
+ Certificate ::= Certificate OPTIONAL
+ AlgorithmIdentifier ::= SEQUENCE {
+ algorithm OBJECT IDENTIFIER,
+ parameters ANY DEFINED BY algorithm OPTIONAL
+ }
+ AuthenticatedAttributes ::= SEQUENCE {
+ target CHARACTER STRING,
+ length INTEGER
+ }
+
+ Signature ::= OCTET STRING
+ END
+</pre>
+
+<p>The <code>Certificate</code> field is the full X.509 certificate containing
+the public key used for signing, as defined by <a
+href="http://tools.ietf.org/html/rfc5280#section-4.1.1.2">RFC5280</a> section
+4.1. When LOCKED, the bootloader must always use the OEM key for verification
+first, and only boot to YELLOW or RED states if the embedded certificate is
+used for verification instead.</p>
+
+<p>The remaining structure is similar to that defined by <a
+href="http://tools.ietf.org/html/rfc5280#section-4.1.1.2">RFC5280</a> sections
+4.1.1.2 and 4.1.1.3 with the exception of the
+<code>AuthenticatedAttributes</code> field. This field contains the length of
+the image to be verified as an integer and the partition where the image can
+be found (boot, recovery, etc.).</p>
+
+<h3 id=signing_and_verifying_an_image>Signing and verifying an image</h3>
+
+<p>To produce a signed image:</p>
+<ol>
+ <li>Generate the unsigned image.
+ <li>0-pad the image to the next page size boundary (omit this step if already
+aligned).
+ <li>Populate the fields of the <code>AuthenticatedAttributes</code> section
+ above based on the padded image and desired target partition.
+ <li>Append the <code>AuthenticatedAttributes</code> structure above to the image.
+ <li>Sign the image.
+</ol>
+
+<p>To verify the image:</p>
+<ol>
+ <li>Determine the size of the image to be loaded including padding (eg, by reading
+a header).
+ <li>Read the signature located at the offset above.
+ <li>Validate the contents of the <code>AuthenticatedAttributes</code> field.
+ If these values do not validate, treat it as a signature validation error.
+ <li>Verify the image and <code>AuthenticatedAttributes</code> sections.
+</ol>
+
+<h3 id=user_experience>User experience</h3>
+
+<p>A user in the GREEN boot state should see no additional user interaction besides that
+required by normal device boot. In other boot states, the user must see a
+warning for at least five seconds. Should the user interact with the device during
+this time, the warning must remain visible at least 30 seconds longer, or until
+the user dismisses the warning.</p>
+
+<p>Sample user interaction screens for other states are shown in the following table:</p>
+
+<p class="table-caption" id="table5">
+ <strong>Table 5.</strong> Sample user interaction screens</p>
+
+<table>
+ <tr>
+ <td>
+<p><strong>Device state</strong></p>
+</td>
+ <td>
+<p><strong>Sample UX</strong></p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>YELLOW (before and after user interaction)</p>
+</td>
+ <td>
+<img src="../images/boot_yellow1.png" alt="Yellow device state 1" id="figure4" />
+<p class="img-caption"><strong>Figure 3.</strong> Yellow state example 1 UI</p>
+</td>
+ <td>
+<img src="../images/boot_yellow2.png" alt="Yellow device state 2" id="figure5" />
+<p class="img-caption"><strong>Figure 4.</strong> Yellow state example 2 UI</p>
+</td>
+
+ </tr>
+ <tr>
+ <td>
+<p>ORANGE</p>
+</td>
+ <td>
+<img src="../images/boot_orange.png" alt="Orange device state" id="figure6" />
+<p class="img-caption"><strong>Figure 5.</strong> Orange state example UI</p>
+</td>
+ </tr>
+ <tr>
+ <td>
+<p>RED</p>
+</td>
+ <td>
+<img src="../images/boot_red.png" alt="Red device state" id="figure7" />
+<p class="img-caption"><strong>Figure 6.</strong> Red state example UI</p>
+</td>
+ </tr>
+</table>
